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