1    /* 
     2     *  Copyright (c) 2009 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     *  ======== ITarget2.xdc ========
    14     */
    15    package xdc.bld;
    16    
    17    /*!
    18     *  ======== ITarget2 ========
    19     *  Extension of the interface {@link xdc.bld.ITarget}.
    20     *
    21     *  This interface contains some common structures and config parameters
    22     *  shared by several packages that contain targets.
    23     */
    24    metaonly interface ITarget2 inherits ITarget {
    25    
    26        /*!
    27         *  ======== Command ========
    28         *  Required command and options.
    29         *
    30         *  The compile, link, and archive functions in this interface are
    31         *  implemented by expanding the strings specified in this structure
    32         *  and inserting strings from the Options structure to form a single
    33         *  command.  The strings in this structure can not be changed by
    34         *  the user (they are fixed by the target), but the string in the
    35         *  Options structure may be changed by the user.
    36         *
    37         *  The final command is:
    38         *      Command.cmd Options.prefix Command.opts Options.suffix
    39         *
    40         *  @field(cmd)     name of a tool-chain executable without any path
    41         *                  information.  The location of this executable is
    42         *                  specified by the binDir (or pathPrefix) 
    43         *                  configuration parameter.
    44         *
    45         *  @field(opts)    required options passed to the command; these options
    46         *                  can not be changed or eliminated by user's
    47         *                  configuration script.
    48         */
    49        struct Command {
    50            string cmd;     /*! the command to run */
    51            string opts;    /*! required options for the command */
    52        }
    53    
    54        /*!
    55         *  ======== Options ========
    56         *  User configurable command options.
    57         *
    58         *  The option strings allow the user to pass additional parameters to the
    59         *  executable that is responsible for compiling, linker, or archiving.
    60         *  See `{@link #Command xdc.bld.ITarget2.Command}`.
    61         */
    62        struct Options {
    63            string prefix;  /*! options that appear before Command.opts */
    64            string suffix;  /*! options that appear after Command.opts */
    65        }
    66    
    67        /*!
    68         *  ======== ar ========
    69         *  The command used to create an archive
    70         */
    71        readonly config Command ar;
    72    
    73        /*!
    74         *  ======== arOpts ========
    75         *  User configurable archiver options.
    76         */
    77        config Options arOpts = {
    78            prefix: "",
    79            suffix: ""
    80        };
    81    
    82        /*!
    83         *  ======== lnk ========
    84         *  The command used to link executables.
    85         */
    86        readonly config Command lnk;
    87    
    88        /*!
    89         *  ======== lnkOpts ========
    90         *  User configurable linker options.
    91         */
    92        config Options lnkOpts = {
    93            prefix: "",
    94            suffix: ""
    95        };
    96    
    97        /*!
    98         *  ======== cc ========
    99         *  The command used to compile C/C++ source files into object files
   100         */
   101        readonly config Command cc;
   102    
   103        /*!
   104         *  ======== ccOpts ========
   105         *  User configurable compiler options.
   106         */
   107        config Options ccOpts = {
   108            prefix: "",
   109            suffix: ""
   110        };
   111    
   112        /*!
   113         *  ======== ccConfigOpts ========
   114         *  User configurable compiler options for the generated config C file.
   115         *
   116         *  By default, this parameter inherits values specified in
   117         *  `{@link #ccOpts ccOpts}`.  The strings `"$(ccOpts.prefix)"` and
   118         *  `"$(ccOpts.suffix)"` are expanded into the values specified by
   119         *  `{@link #ccOpts ccOpts}` for this target.
   120         */
   121        config Options ccConfigOpts = {
   122            prefix: "$(ccOpts.prefix)",
   123            suffix: "$(ccOpts.suffix)"
   124        };
   125    
   126        /*!
   127         *  ======== asm ========
   128         *  The command used to assembles assembly source files into object files
   129         */
   130        readonly config Command asm;
   131    
   132        /*!
   133         *  ======== asmOpts ========
   134         *  User configurable assembler options.
   135         */
   136        config Options asmOpts = {
   137            prefix: "",
   138            suffix: ""
   139        };
   140    
   141        /*!
   142         *  ======== includeOpts ========
   143         *  Additional user configurable target-specific include path options
   144         */
   145        config string includeOpts;
   146    
   147        /*!
   148         *  ======== genConstCustom ========
   149         *  Return any custom generated code related to generated constants
   150         *
   151         *  This function is invoked for each constant in the generated config C
   152         *  file. This includes module-level config parameter, as well as the
   153         *  internal data structures that define modules, interfaces and instances.
   154         *  A target is given a chance to add any target-specific pragmas or
   155         *  attributes for the generated constants. The set of the data supplied to
   156         *  this function overlaps with the data supplied to
   157         *  `{@link genVisibleData genVisibleData}`, so their output must be
   158         *  coordinated to avoid duplicate or inconsistent definitions or
   159         *  directives.
   160         *
   161         *  @params(names)  array of constant names generated in the
   162         *                  config C file
   163         *
   164         *  @params(types)  array of types; each type corresponds to the element
   165         *                  of `names` with the same index
   166         *
   167         *  @a(returns)
   168         *  This function returns custom C code that will be embedded into the
   169         *  generated config C file. If there is nothing to be added, this function
   170         *  returns `null`. If a target never generates any such code, it can rely
   171         *  on the default implementation that always returns `null`.
   172         */
   173        String genConstCustom(StringArray names, StringArray types);
   174    
   175        /*!
   176         *  ======== genVisibleData ========
   177         *  Return any custom generated code related to data generated in the
   178         *  config C file
   179         *
   180         *  This function is invoked for each module-level configuration parameter
   181         *  in the configuration. Such parameters are represented by constants in the
   182         *  generated config C file.
   183         
   184         *  A target is given a chance to add any target-specific pragmas or
   185         *  attributes for the generated constants. The set of the data supplied to
   186         *  this function overlaps with the data supplied to
   187         *  `{@link genConstCustom genConstCustom}`, so their output must be
   188         *  coordinated to avoid duplicate or inconsistent definitions or
   189         *  directives.
   190         *
   191         *  @params(quals)          array of declaration qualifiers for the
   192         *                          generated data
   193         *
   194         *  @params(types)          array of types for the generated data
   195         *
   196         *  @params(names)          array of variable names; each name corresponds
   197         *                          to the elements of `quals` and `types` with the
   198         *                          same index
   199         *
   200         *  @a(returns)
   201         *  This function returns custom C code that will be embedded into the
   202         *  generated config C file. The purpose of the function is to allow
   203         *  targets to add pragmas or attributes to prevent elimination of data
   204         *  in case of partially linker objects.
   205         *  If there is nothing to be added, this function returns `null`. If a
   206         *  target never generates any such code, it can rely on the default
   207         *  implementation that always returns `null`.
   208         */
   209        String genVisibleData(StringArray quals, StringArray types,
   210                              StringArray names);
   211        /*!
   212         *  ======== genVisibleFxns ========
   213         *  Return any custom generated code related to functions generated in
   214         *  the config C file
   215         *
   216         *  @params(types)          array of types of functions' return values
   217         *
   218         *  @params(names)          array of functions' names; each name corresponds
   219         *                          to the elements of `types` and `args` with the
   220         *                          same index
   221         *
   222         *  @params(args)           array of functions' argument lists, including
   223         *                          qualifiers
   224         
   225         *  @a(returns)
   226         *  This function returns custom C code that will be embedded into the
   227         *  generated config C file. The purpose of the function is to allow
   228         *  targets to add pragmas or attributes to prevent elimination of functions
   229         *  in case of partially linker objects.
   230         */
   231        String genVisibleFxns(StringArray types, StringArray names,
   232                              StringArray args);
   233    
   234        /*!
   235         *  ======== genVisibleLibFxns ========
   236         *  Return any custom generated code related to functions that are included
   237         *  in the configuration, but are not generated in the config C file
   238         *
   239         *  @params(types)          array of types of functions' return values
   240         *
   241         *  @params(names)          array of functions' names; each name corresponds
   242         *                          to the elements of `types` and `args` with the
   243         *                          same index
   244         *
   245         *  @params(args)           array of functions' argument lists, including
   246         *                          qualifiers
   247         
   248         *  @a(returns)
   249         *  This function returns custom C code that will be embedded into the
   250         *  generated config C file. The purpose of the function is to allow
   251         *  targets to add pragmas or attributes to prevent elimination of functions
   252         *  in case of partially linker objects. These functions are managed
   253         *  separately from the functions that are generated in the config C file
   254         *  because some pragmas and attributes can be used only for functions
   255         *  defined in the same compilation unit where the paragmas and attributes
   256         *  are generated. For functions that are not generated in the config C
   257         *  file, and the mentioned restrictions exist, targets may have to create
   258         *  references that will prevent elimination of functions defined outside
   259         *  of the config C file.
   260         */
   261        String genVisibleLibFxns(StringArray types, StringArray names,
   262                                 StringArray args);
   263    }
   264    /*
   265     *  @(#) xdc.bld; 1, 0, 2,475; 3-20-2014 17:05:09; /db/ztree/library/trees/xdc/xdc-A32x/src/packages/
   266     */
   267