1 2 3 4 5 6 7 8 9 10 11
12 /*!
13 * ======== xdc ========
14 * Core interfaces and modules necessary for the XDC runtime.
15 *
16 * In addition to the interfaces specified below, this package also supplies
17 * a C/C++ header, `std.h` that facilitates the creation of portable sources.
18 * This header defines a set of "base" types that enable the creation
19 * of C-code that is portable between any two targets. C source code that
20 * relies exclusively on these types is portable to all targets and
21 * platforms. Where appropriate, the types defined below are related to the
22 * types defined in the library headers prescribed by the C99 standard
23 * (ISO/IEC 9899:1999).
24 *
25 * Why not simply use the C99 types? Having a
26 * unique set of names provides a layer of insulation between a portable code
27 * base and a particular compiler; e.g., even if a compiler does not support
28 * the C99 types or defines them inappropriately for a particular device, it
29 * is possible to use the compiler without changing the code base. Thus, the
30 * developer is not forced to choose the lesser of two evils: waiting for a
31 * change to the compiler or forking the code base for a particular compiler
32 * device combination.
33 *
34 * There are several situations where a small separate set of portable types
35 * can help the maintainability of a code base.
36 * @p(blist)
37 * - not all of the types described in the C99 standard are required to
38 * be defined by conformant implementations nor is it possible for all
39 * devices to implement some of the types specified (e.g., `int8_t` is
40 * not implemented on C54 devices); so it is difficult to identify
41 * non-portable source code.
42 * - not all compilers provide C99 type support; if XDC supplies the type
43 * definition and the compiler is updated to include C99 types, a
44 * compilation error will occur if the source includes the C99
45 * headers.
46 * - not all compiler and device combinations are conformant; even high
47 * quality compilers may not properly define the types for each device
48 * supported by compiler.
49 *
50 * @a(Usage)
51 * @p(code)
52 * #include <xdc/std.h>
53 * @p
54 *
55 * To compile sources that include `xdc/std.h`, two symbols must be defined
56 * before including this header:
57 * @p(dlist)
58 * - `xdc_target_types__`
59 * the package qualified path of the target's standard types header;
60 * e.g., `ti/targets/std.h`. This value is specified in the target's
61 * `stdInclude` config parameter; see
62 * `{@link xdc.bld.ITarget#stdInclude}`
63 *
64 * - `xdc_target_name__`
65 * the target's module name without the package prefix; e.g., `C64`
66 * rather than `ti.targets.C64`.
67 * @p
68 * For example, to compile sources for the `ti.targets.C64` target using TI's
69 * `cl6x` compiler, the following command line is sufficient:
70 * @p(code)
71 * cl6x -Dxdc_target_types__=ti/targets/std.h -Dxdc_target_name__=C64
72 * @p
73 *
74 * Each of the type names below has an equivalent "long name"; i.e., a name
75 * that has an "`xdc_`" prefix. For example, the type `Bool` can also be
76 * written as "`xdc_Bool`". Long names exist to avoid conflicts with
77 * names defined or used by existing code bases.
78 *
79 * In the event that one of the short type names below conflicts with another
80 * type name (that can not be changed), it is possble to disable the short
81 * names by defining the symbol `xdc__nolocalnames` before including
82 * `xdc/std.h`.
83 * @p(code)
84 * #define xdc__nolocalnames
85 * #include <xdc/std.h>
86 * @p
87 *
88 * There are two other symbols that affect the definitions provided by
89 * `std.h`: `xdc__strict` and `xdc__deprecated_types`. These symbols, like
90 * `xdc__nolocalnames`, enable you to easily control the definitions provided
91 * `std.h`. In this case, however, these symbols are used to manage the
92 * deprecation of symbols provided in earlier releases. For more information
93 * about when to use these symbols, see {@link http://rtsc.eclipse.org/docs-tip/Integrating_RTSC_Modules#Disabling_and_Enabling_Deprecated_Definitions Disabling and Enabling Deprecated Definitions}`.
94 *
95 * @a(Standard Types)
96 * This header may be included multiple times and defines the following
97 * target-dependent types:
98 * @p(dlist)
99 * - `Bool`
100 * this type is large enough to hold the values `0` or `1`. The
101 * constants TRUE and FALSE are of this type; see below.
102 * - `String`
103 * this type is defined to be a `char *` and exists to allow code
104 * to distinguish between pointers to buffers of raw data and
105 * '\0' terminated strings.
106 * - `CString`
107 * this type is defined to be a `const char *` and exists to allow
108 * code to distinguish between pointers to a modifiable '\0'
109 * terminated sequence of characters (i.e., a `String`) and one that
110 * is not modifiable (e.g., a literal string such as
111 * `"hello world\n"`).
112 * - `Int`n, where n = 8, 16, or 32
113 * signed integer type that is large enough to hold n bits; the
114 * actual target type may by be larger than n. This type is
115 * equivalent to one of the C99 types `int_least`n`_t` or
116 * `int_fast`n`_t`; see Section 7.18.
117 * - `UInt`n, where n = 8, 16, or 32
118 * unsigned integer type that is large enough to hold n bits; the
119 * actual target type may by be larger than n. This type is
120 * equivalent to one of the C99 types `uint_least`n`_t` or
121 * `uint_fast`n`_t`; see ISO/IEC 9899:1999 Section 7.18.
122 * - `Bits`n, where n = 8, 16, or 32
123 * unsigned integer type that is precisely n bits. Not all targets
124 * support all values of n; if the target does not support an exact
125 * size the corresponding type is not defined. This type is
126 * equivalent to the corresponding C99 type `uint`n`_t`; see ISO/IEC
127 * 9899:1999 Section 7.18.
128 * - `Fxn`
129 * this type is a pointer to code; it can hold a pointer to any
130 * function.
131 * - `Ptr`
132 * this type is a pointer to data; it can hold a pointer to any
133 * data structure.
134 * - `IArg`
135 * this integer type is large enough to hold a `Fxn`, `Ptr`, or
136 * `Int`.
137 * - `UArg`
138 * this unsigned integer type is large enough to hold a `Fxn`,
139 * `Ptr`, or `Int`.
140 * - `LLong`
141 * this long integer type is large enough to hold a `Long` and is
142 * defined as a 'long long' type on targets that support this type;
143 * otherwise, it is simply a `Long`.
144 *
145 * Note that C99 requires the `long long` type to be at least 64-bits
146 * wide (See ISO/IEC 9899:1999 Section 5.2.4.2.1). But some
147 * compilers do not support 64-bit integral types and some don't
148 * support the `long long` even though they do support 64-bit
149 * integral types. Since these variations limit the portability of
150 * valid C sources, the LLong type is always defined, is always at
151 * least as wide as the `Long` type, and is at least 64-bits wide for
152 * targets that support 64-bit integral types.
153 *
154 * - `ULLong`
155 * this unsigned long integer type is large enough to hold a `ULong`
156 * and is defined as a 'unsigned long long' type on targets that
157 * support this type; otherwise, it is simply a `ULong`.
158 * @p
159 *
160 * The `xdc/std.h` header also defines the following aliases for the base C
161 * types. These aliases exist so that C sources can consistently follow
162 * a naming convention in which all type names are written in camel-case.
163 * @p(dlist)
164 * - `Char` and `UChar`
165 * aliases for `char` and `unsigned char`, respectively
166 * - `Short` and `UShort`
167 * aliases for `short` and `unsigned short`, respectively
168 * - `Int` and `UInt`
169 * aliases for `int` and `unsigned int`, respectively
170 * - `Long` and `ULong`
171 * aliases for `long` and `unsigned long`, respectively
172 * - `Double` and `LDouble`
173 * aliases for `double` and `long double`, respectively
174 * - `SizeT`
175 * alias for `size_t`
176 * - `VaList`
177 * alias for `va_list`
178 * @p
179 * The types above are defined for all targets. Some targets can support
180 * the following additional types. Since these types are not always
181 * supported by a target, these types should only be used when no other
182 * type sufficies.
183 * @p(dlist)
184 * - `Bits`n, where n = 8, 16, or 32
185 * this unsigned integer type is precisely n-bits wide. This type is
186 * equivalent to the optional C99 type `uint`n`_t`; see ISO/IEC
187 * 9899:1999 Section 7.18.1.1. This type is defined if and
188 * only if the preprocessor macro `xdc__BITS`n`__` is defined.
189 * @p
190 *
191 * @a(64 Bit Types)
192 * Although the C99 standard requires support for 64-bit types, not all
193 * compiler/device combinations can usefully support them. As a result,
194 * the 64-bit types described here may not be defined for all targets. For
195 * each type there is a corresponding pre-processor macro which is
196 * defined if and only if the type is supported.
197 * @p(dlist)
198 * - `Int64`
199 * signed integer type that is large enough to hold 64 bits; the
200 * actual target type may by be wider than 64 bits. This type is
201 * equivalent to one of the C99 types `int_least64_t` or
202 * `int_fast64_t`; see Section 7.18. This type is defined if and
203 * only if the preprocessor macro `xdc__INT64__` is defined.
204 * - `UInt64`
205 * unsigned integer type that is large enough to hold n bits; the
206 * actual target type may by be wider than 64 bits. This type is
207 * equivalent to one of the C99 types `uint_least64_t` or
208 * `uint_fast64_t`; see ISO/IEC 9899:1999 Section 7.18. This type
209 * is defined if and only if the preprocessor macro
210 * `xdc__INT64__` is defined.
211 * - `Bits64`
212 * unsigned integer type that is precisely 64 bits wide. If the target
213 * does not support an exact 64-bit size, this type is not defined.
214 * This type is equivalent to the corresponding C99 type
215 * `uint64_t`; see ISO/IEC 9899:1999 Section 7.18. This type is
216 * defined if and only if the preprocessor macro `xdc__BITS64__` is
217 * defined.
218 * @p
219 *
220 * @a(Predefined Macros)
221 * In addition to the type definitions above, `xdc/std.h` also defines the
222 * following commonly used constants
223 * @p(dlist)
224 * - `NULL`
225 * defined as `0`
226 * - `TRUE`
227 * defined as `((Bool)1)`
228 * - `FALSE`
229 * defined as `((Bool)0)`
230 * @p
231 *
232 * Finally, `xdc/std.h` defines the following target-independent symbols
233 * that have target-dependent values; these predefined macros enable
234 * conditional compilation of source files based on target-specific
235 * attributes.
236 * @p(dlist)
237 * - {c_target_name}
238 * this symbol (the target's fully qualified name with all '.'s
239 * replaced with '_') is always defined and allows one to easily
240 * include target-specific headers or define symbols with
241 * target-specific values.
242 *
243 * - `xdc_target__isaCompatible_`{isa_name}
244 * for every ISA named in the array returned by this target's
245 * `{@link xdc.bld.ITarget#getISAChain()}` method, a symbol of this
246 * name is defined. In addition to enabling one to create code
247 * specific to a particular ISA, this allows one to create code that
248 * depends on TI's C6x architecture without being dependent
249 * on a particular member of the C6x family, for example.
250 *
251 * - `xdc_target__isa_`{isa}
252 * this symbol is always defined and {isa} is the
253 * target's `isa` (see `{@link xdc.bld.ITarget#isa}`).
254 *
255 * - `xdc_target__`{little,big}`Endian`
256 * if this target's `{@link xdc.bld.ITarget#model}.endian` property is
257 * specified, this symbol is defined and {little,big} is replaced
258 * by `model.endian`.
259 *
260 * - `xdc_target__`{code_model_name}`Code`
261 * if this target's `{@link xdc.bld.ITarget#model}.codeModel` is
262 * specified, this symbol is defined and {code_model_name} is
263 * replaced by `model.codeModel`.
264 *
265 * - `xdc_target__`{data_model_name}`Data`
266 * if this target's `{@link xdc.bld.ITarget#model}.dataModel` is
267 * specified, this symbol is defined and {data_model_name} is
268 * replaced by `model.dataModel`.
269 *
270 * - `xdc_target__os_`{os_name}
271 * this symbol is always defined and {os_name} is the
272 * target's os name (see `{@link xdc.bld.ITarget#os}`).
273 *
274 * - `xdc_target__sizeof_`{type_name}
275 * this symbol is defined for each type name supported in the target's
276 * `{@link xdc.bld.ITarget#stdTypes}` structure, {type_name} is the
277 * name of one of the standard types supported above, and the
278 * value is `sizeof(type_name)`.
279 *
280 * - `xdc_target__alignof_`{type_name}
281 * this symbol is defined for each type name supported in the target's
282 * `{@link xdc.bld.ITarget#stdTypes}` structure, {type_name} is the
283 * name of one of the standard types supported above, and the
284 * value is the alignment required by the compiler for {type_name}.
285 *
286 * - `xdc_target__bitsPerChar`
287 * this symbol is always defined and specifies the number of bits
288 * in the target's `char`. This value combined with the
289 * `xdc_target__sizeof_` values allows C code to determine the
290 * precise number of bits in any of the standard types.
291 * @p
292 *
293 * @a(See)
294 * {@link http://www.open-std.org/jtc1/sc22/wg14/www/standards ISO-IEC JTC1-SC22-WG14 - C Approved standards}
295 *
296 * @a(Throws)
297 * `XDCException` exceptions are thrown for fatal errors. The following
298 * error codes are reported in the exception message:
299 * @p(dlist)
300 * - `xdc.PACKAGE_NOT_FOUND`
301 * This error is reported whenever a specified package is not found
302 * This may happen for the following reasons:
303 * @p(blist)
304 * - Ensure that the package in question is contained in one of
305 * the repositories named in the package path.
306 * - The package has not been built by the `xdc` tool even though
307 * the physical package directory may be present along the
308 * package path
309 * @p(dlist)
310 * - `xdc.FILE_NOT_FOUND`
311 * This error is reported when a specified file is not found.
312 * Ensure that any directory name prefix in the name is a package
313 * directory contained in one of the repositories named in the
314 * package path. For example, if "ti/targets/linkcmd.xdt" can't
315 * be found, make sure the directory `ti/targets/` is contained in
316 * at least one repository named in the package path.
317 * - `xdc.MODULE_NOT_FOUND`
318 * This error is reported when a specified module can't be
319 * found. Ensure that the package containing the module in
320 * question is contained in at least one repository named in
321 * the package path.
322 * Also ensure that the module name is qualified with the
323 * package name. For example, to refer to the module `Engine`
324 * in the package `ti.sdo.ce`, the module name should be
325 * specified as `ti.sdo.ce.Engine`.
326 * - `xdc.TOOL_USAGE_ERROR`
327 * This error may happen when the `xs` tool is not passed the
328 * expected command line arguments.
329 * - `xdc.MODULE_UNDEFINED_MAIN_FUNCTION`
330 * This error is reported when the `xs` tool is passed a module
331 * that does not define a `main` function. Ensure that the
332 * meta-domain implementation of the module has a `main` function.
333 * - `xdc.SPEC_FILE_ERROR`
334 * This error is reported when there is a parsing error in a
335 * specification file. Check the spec. file for syntax errors.
336 * - `xdc.DEPRECATED_FUNCTION`
337 * This error is reported whenever a deprecated function is called.
338 * - `xdc.STATIC_INSTANCE`
339 * This error is reported when a function create() is called at the
340 * configuration time for a module that does not implement the
341 * function instance$static$init and therefore does not support
342 * static instances.
343 */
344 package xdc [1,1,1] {
345
346 interface IPackage;
347 module Warnings;
348 }
349 350 351
352