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 * @a(Standard Types)
89 * This header may be included multiple times and defines the following
90 * target-dependent types:
91 * @p(dlist)
92 * - `Bool`
93 * this type is large enough to hold the values `0` or `1`. The
94 * constants TRUE and FALSE are of this type; see below.
95 * - `String`
96 * this type is defined to be a `char *` and exists to allow code
97 * to distinguish between pointers to buffers of raw data and
98 * '\0' terminated strings.
99 * - `Int`n, where n = 8, 16, or 32
100 * signed integer type that is large enough to hold n bits; the
101 * actual target type may by be larger than n. This type is
102 * equivalent to one of the C99 types `int_least`n`_t` or
103 * `int_fast`n`_t`; see Section 7.18.
104 * - `UInt`n, where n = 8, 16, or 32
105 * unsigned integer type that is large enough to hold n bits; the
106 * actual target type may by be larger than n. This type is
107 * equivalent to one of the C99 types `uint_least`n`_t` or
108 * `uint_fast`n`_t`; see ISO/IEC 9899:1999 Section 7.18.
109 * - `Bits`n, where n = 8, 16, or 32
110 * unsigned integer type that is precisely n bits. Not all targets
111 * support all values of n; if the target does not support an exact
112 * size the corresponding type is not defined. This type is
113 * equivalent to the corresponding C99 type `uint`n`_t`; see ISO/IEC
114 * 9899:1999 Section 7.18.
115 * - `Fxn`
116 * this type is a pointer to code; it can hold a pointer to any
117 * function.
118 * - `Ptr`
119 * this type is a pointer to data; it can hold a pointer to any
120 * data structure.
121 * - `IArg`
122 * this integer type is large enough to hold a `Fxn`, `Ptr`, or
123 * `Int`.
124 * - `UArg`
125 * this unsigned integer type is large enough to hold a `Fxn`,
126 * `Ptr`, or `Int`.
127 * - `LLong`
128 * this long integer type is large enough to hold a `Long` and is
129 * defined as a 'long long' type on targets that support this type;
130 * otherwise, it is simply a `Long`.
131 *
132 * Note that C99 requires the `long long` type to be at least 64-bits
133 * wide (See ISO/IEC 9899:1999 Section 5.2.4.2.1). But some
134 * compilers do not support 64-bit integral types and some don't
135 * support the `long long` even though they do support 64-bit
136 * integral types. Since these variations limit the portability of
137 * valid C sources, the LLong type is always defined, is always at
138 * least as wide as the `Long` type, and is at least 64-bits wide for
139 * targets that support 64-bit integral types.
140 *
141 * - `ULLong`
142 * this unsigned long integer type is large enough to hold a `ULong`
143 * and is defined as a 'unsigned long long' type on targets that
144 * support this type; otherwise, it is simply a `ULong`.
145 * @p
146 *
147 * The `xdc/std.h` header also defines the following aliases for the base C
148 * types. These aliases exist so that C sources can consistently follow
149 * a naming convention in which all type names are written in camel-case.
150 * @p(dlist)
151 * - `Char` and `UChar`
152 * aliases for `char` and `unsigned char`, respectively
153 * - `Short` and `UShort`
154 * aliases for `short` and `unsigned short`, respectively
155 * - `Int` and `UInt`
156 * aliases for `int` and `unsigned int`, respectively
157 * - `Long` and `ULong`
158 * aliases for `long` and `unsigned long`, respectively
159 * - `Double` and `LDouble`
160 * aliases for `double` and `long double`, respectively
161 * - `SizeT`
162 * alias for `size_t`
163 * - `VaList`
164 * alias for `va_list`
165 * @p
166 * The types above are defined for all targets. Some targets can support
167 * the following additional types. Since these types are not always
168 * supported by a target, these types should only be used when no other
169 * type sufficies.
170 * @p(dlist)
171 * - `Bits`n, where n = 8, 16, or 32
172 * this unsigned integer type is precisely n-bits wide. This type is
173 * equivalent to the optional C99 type `uint`n`_t`; see ISO/IEC
174 * 9899:1999 Section 7.18.1.1. This type is defined if and
175 * only if the preprocessor macro `xdc__BITS`n`__` is defined.
176 * @p
177 *
178 * @a(64-Bit Types)
179 * Although the C99 standard requires support for 64-bit types, not all
180 * compiler/device combinations can usefully support them. As a result,
181 * the 64-bit types described here may not be defined for all targets. For
182 * each type there is a corresponding pre-processor macro which is
183 * defined if and only if the type is supported.
184 * @p(dlist)
185 * - `Int64`
186 * signed integer type that is large enough to hold 64 bits; the
187 * actual target type may by be wider than 64 bits. This type is
188 * equivalent to one of the C99 types `int_least64_t` or
189 * `int_fast64_t`; see Section 7.18. This type is defined if and
190 * only if the preprocessor macro `xdc__INT64__` is defined.
191 * - `UInt64`
192 * unsigned integer type that is large enough to hold n bits; the
193 * actual target type may by be wider than 64 bits. This type is
194 * equivalent to one of the C99 types `uint_least64_t` or
195 * `uint_fast64_t`; see ISO/IEC 9899:1999 Section 7.18. This type
196 * is defined if and only if the preprocessor macro
197 * `xdc__INT64__` is defined.
198 * - `Bits64`
199 * unsigned integer type that is precisely 64 bits wide. If the target
200 * does not support an exact 64-bit size, this type is not defined.
201 * This type is equivalent to the corresponding C99 type
202 * `uint64_t`; see ISO/IEC 9899:1999 Section 7.18. This type is
203 * defined if and only if the preprocessor macro `xdc__BITS64__` is
204 * defined.
205 * @p
206 *
207 * @a(Predefined Macros)
208 * In addition to the type definitions above, `xdc/std.h` also defines the
209 * following commonly used constants
210 * @p(dlist)
211 * - `NULL`
212 * defined as `0`
213 * - `TRUE`
214 * defined as `((Bool)1)`
215 * - `FALSE`
216 * defined as `((Bool)0)`
217 * @p
218 *
219 * Finally, `xdc/std.h` defines the following target-independent symbols
220 * that have target-dependent values; these predefined macros enable
221 * conditional compilation of source files based on target-specific
222 * attributes.
223 * @p(dlist)
224 * - {c_target_name}
225 * this symbol (the target's fully qualified name with all '.'s
226 * replaced with '_') is always defined and allows one to easily
227 * include target-specific headers or define symbols with
228 * target-specific values.
229 *
230 * - `xdc_target__isaCompatible_`{isa_name}
231 * for every ISA named in the array returned by this target's
232 * `{@link xdc.bld.ITarget#getISAChain()}` method, a symbol of this
233 * name is defined. In addition to enabling one to create code
234 * specific to a particular ISA, this allows one to create code that
235 * depends on TI's C6x architecture without being dependent
236 * on a particular member of the C6x family, for example.
237 *
238 * - `xdc_target__isa_`{isa}
239 * this symbol is always defined and {isa} is the
240 * target's `isa` (see `{@link xdc.bld.ITarget#isa}`).
241 *
242 * - `xdc_target__`{little,big}`Endian`
243 * if this target's `{@link xdc.bld.ITarget#model}.endian` property is
244 * specified, this symbol is defined and {little,big} is replaced
245 * by `model.endian`.
246 *
247 * - `xdc_target__`{code_model_name}`Code`
248 * if this target's `{@link xdc.bld.ITarget#model}.codeModel` is
249 * specified, this symbol is defined and {code_model_name} is
250 * replaced by `model.codeModel`.
251 *
252 * - `xdc_target__`{data_model_name}`Data`
253 * if this target's `{@link xdc.bld.ITarget#model}.dataModel` is
254 * specified, this symbol is defined and {data_model_name} is
255 * replaced by `model.dataModel`.
256 *
257 * - `xdc_target__os_`{os_name}
258 * this symbol is always defined and {os_name} is the
259 * target's os name (see `{@link xdc.bld.ITarget#os}`).
260 *
261 * - `xdc_target__sizeof_`{type_name}
262 * this symbol is defined for each type name supported in the target's
263 * `{@link xdc.bld.ITarget#stdTypes}` structure, {type_name} is the
264 * name of one of the standard types supported above, and the
265 * value is `sizeof(type_name)`.
266 *
267 * - `xdc_target__alignof_`{type_name}
268 * this symbol is defined for each type name supported in the target's
269 * `{@link xdc.bld.ITarget#stdTypes}` structure, {type_name} is the
270 * name of one of the standard types supported above, and the
271 * value is the alignment required by the compiler for {type_name}.
272 *
273 * - `xdc_target__bitsPerChar`
274 * this symbol is always defined and specifies the number of bits
275 * in the target's `char`. This value combined with the
276 * `xdc_target__sizeof_` values allows C code to determine the
277 * precise number of bits in any of the standard types.
278 * @p
279 *
280 * @a(See)
281 * {@link http://www.open-std.org/jtc1/sc22/wg14/www/standards ISO-IEC JTC1-SC22-WG14 - C Approved standards}
282 *
283 * @a(Throws)
284 * `XDCException` exceptions are thrown for fatal errors. The following
285 * error codes are reported in the exception message:
286 * @p(dlist)
287 * - `xdc.PACKAGE_NOT_FOUND`
288 * This error is reported whenever a specified package is not found
289 * This may happen for the following reasons:
290 * @p(blist)
291 * - Ensure that the package in question is contained in one of
292 * the repositories named in the package path.
293 * - The package has not been built by the `xdc` tool even though
294 * the physical package directory may be present along the
295 * package path
296 * @p(dlist)
297 * - `xdc.FILE_NOT_FOUND`
298 * This error is reported when a specified file is not found.
299 * Ensure that any directory name prefix in the name is a package
300 * directory contained in one of the repositories named in the
301 * package path. For example, if "ti/targets/linkcmd.xdt" can't
302 * be found, make sure the directory `ti/targets/` is contained in
303 * at least one repository named in the package path.
304 * - `xdc.MODULE_NOT_FOUND`
305 * This error is reported when a specified module can't be
306 * found. Ensure that the package containing the module in
307 * question is contained in at least one repository named in
308 * the package path.
309 * Also ensure that the module name is qualified with the
310 * package name. For example, to refer to the module `Engine`
311 * in the package `ti.sdo.ce`, the module name should be
312 * specified as `ti.sdo.ce.Engine`.
313 * - `xdc.TOOL_USAGE_ERROR`
314 * This error may happen when the `xs` tool is not passed the
315 * expected command line arguments.
316 * - `xdc.MODULE_UNDEFINED_MAIN_FUNCTION`
317 * This error is reported when the `xs` tool is passed a module
318 * that does not define a `main` function. Ensure that the
319 * meta-domain implementation of the module has a `main` function.
320 * - `xdc.SPEC_FILE_ERROR`
321 * This error is reported when there is a parsing error in a
322 * specification file. Check the spec. file for syntax errors.
323 * - `xdc.DEPRECATED_FUNCTION`
324 * This error is reported whenever a deprecated function is called.
325 * - `xdc.STATIC_INSTANCE`
326 * This error is reported when a function create() is called at the
327 * configuration time for a module that does not implement the
328 * function instance$static$init and therefore does not support
329 * static instances.
330 */
331 package xdc [1,1,1] {
332
333 interface IPackage;
334 }
335 336 337
338