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     *  ======== Program.xdc ========
    14     */
    15    package xdc.cfg;
    16    
    17    /*!
    18     *  ======== Program ========
    19     *  The Program object for the configuration object model.
    20     *
    21     *  This module defines the "root" of the configuration object model; all
    22     *  "top-level" configuration settings for the executable are provided by
    23     *  this object. Program configuration scripts reference this module via the
    24     *  global variable `Program`; i.e., `Program` is implicitly initialized as
    25     *  follows:
    26     *  @p(code)
    27     *      var Program = xdc.useModule('xdc.cfg.Program');
    28     *  @p
    29     *
    30     *  After a configuration script completes successfully, the following files
    31     *  are generated:
    32     *  @p(nlist)
    33     *      - package/cfg/<exe_name>.c
    34     *      - package/cfg/<exe_name>.xdl
    35     *  @p
    36     *  where `<exe_name>` is the name of the executable with the final '.'
    37     *  character replaced with an '_'.
    38     *
    39     *  The generated C file contains code and data from each module used by the
    40     *  program and must be compiled and linked with the other sources to
    41     *  produce the final executable.  The generated linker command file must also
    42     *  be added during this final link step.
    43     *
    44     *  The linker command file is produced by expanding a template
    45     *  provided by the platform specifed during configuration and contains
    46     *  hardware and compiler specific directives required by the target modules
    47     *  that are part of the program's configuration.  This template expands
    48     *  other templates specified by each imported package's
    49     *  `{@link xdc.IPackage#getSects getSects}` method, for example. This allows
    50     *  each package participating in the configuration executable to
    51     *  automatically contribute a portion of the executable's linker command
    52     *  file.
    53     *
    54     *  You can modify or augment the contents of this file via
    55     *  `{@link xdc.cfg.Program#sectionsExclude sectionsExclude}` and
    56     *  `{@link xdc.cfg.Program#sectionsTemplate sectionsTemplate}`. It is even
    57     *  possible to completely replace the template used to generate this file via
    58     *  `{@link xdc.cfg.Program#linkTemplate linkTemplate}`. If a custom template
    59     *  is used, it should still invoke `{@link xdc.IPackage#getSects getSects}`
    60     *  methods for all loaded packages.
    61     *  These configuration options provide the user complete control of the linker
    62     *  command file.
    63     */
    64    
    65    @Template("./Program.xdt")
    66    
    67    metaonly module Program {
    68    
    69        /*!
    70         *  ======== GenerationOptions ========
    71         *  Options that control the files generated as part of program
    72         *  configuration.
    73         *
    74         *  @field(debuggerFiles) If set to `true` in a configuration script,
    75         *          debugger project files will be generated as part of the
    76         *          configuration step.  If set to `false`, these files will not
    77         *          be generated.
    78         *
    79         *          If it is not set (or set to undefined) and the environment
    80         *          variable `environment["xdc.cfg.gen.debuggerFiles"]` is
    81         *          non-`null`, then the default value of this parameter is taken
    82         *          to be the value of the following expression:
    83         *          @p(code)
    84         *              environment["xdc.cfg.gen.debuggerFiles"] == "true"
    85         *          @p
    86         *          This makes it is possible to enable the generation of
    87         *          debugger project files from build scripts by passing
    88         *          the option `-Dxdc.cfg.gen.debuggerFiles=true` to the
    89         *          configuration tool (see
    90         *          `{@link xdc.bld.Executable#Attrs.xsopts}` or
    91         *          `{@link xdc.bld.PackageContents#Attrs.xsopts}`).
    92         *
    93         *          Finally, if `debuggerFiles` is not set (or set to `undefined`)
    94         *          and the environment variable above is not defined,
    95         *          the generation of debugger project files occurs only if
    96         *          `{@link xdc.cfg.Program#build.profile}` contains
    97         *          the string `"debug"`.  So, unless otherwise specified, debug
    98         *          profiles result in debugger project files being generated.
    99         */
   100        struct GenerationOptions {
   101            Bool debuggerFiles; /*! if `true`, generate debugger "project" files */
   102        };
   103    
   104        /*!
   105         *  ======== SectionSpec ========
   106         *  Map that instructs the linker where to place output sections.
   107         *
   108         *  This structure contains some fields that are specific to TI targets.
   109         *  On non-TI targets, such fields are ignored.
   110         *
   111         *  @field(runSegment) Defines the memory segment where the section is
   112         *          to be run.
   113         *
   114         *  @field(loadSegment) Defines the memory segment where the section is
   115         *          to be loaded. If 'runSegment' or 'loadSegment' is defined,
   116         *          but not both, the linker is instructed to use the defined
   117         *          field as the load and run allocation for the section.
   118         *
   119         *  @field(runAddress) Defines the memory address where the section is
   120         *          to be run. It is an error if both 'runSegment' and 'runAddress'
   121         *          are specified.
   122         *
   123         *  @field(loadAddress) Defines the memory address where the section is
   124         *          to be loaded. It is an error if both 'loadSegment' and
   125         *          'loadAddress' are specified. If 'runAddress' or 'loadAddress'
   126         *          is defined, but not both, the linker is instructed to use the
   127         *          defined field as the load and run address for the section.
   128         *
   129         *  @field(runAlign) If runSegment is specified, runAlign determines the
   130         *          alignment. It is an error if both 'runAlign' and 'runAddress'
   131         *          are specified.
   132         *
   133         *  @field(loadAlign) If runSegment is specified, runAlign determins the
   134         *          alignment. It is an error if both 'loadAlign' and 'loadAddress'
   135         *          are specified.
   136         *
   137         *  @field(type) Defines flags for special section types (COPY, DSECT,
   138         *          NOLOAD).
   139         *
   140         *  @field(fill) Defines the value to initialize an uninitialized
   141         *  section.
   142         */
   143        struct SectionSpec {
   144            String runSegment;  /*! segment where section contents are run */
   145            String loadSegment; /*! segment where section contents are loaded */
   146            UInt runAddress;    /*! start address of section when run */
   147            UInt loadAddress;   /*! start address of section when loaded */
   148            UInt runAlign;      /*! alignment of section within runSegment */
   149            UInt loadAlign;     /*! alignment of section within loadSegment */
   150            String type;        /*! target-specific flags */
   151            UInt fill;          /*! fill value */
   152        };
   153    
   154        /*!
   155         *  ======== gen ========
   156         *  Generation options for this executable
   157         *
   158         *  This configuration parameter allows the program configuration script
   159         *  to control (to some extent) what files are generated as part of the
   160         *  configuration process.
   161         */
   162        config GenerationOptions gen;
   163    
   164        /*!
   165         *  ======== globalSection ========
   166         *  UNDER CONSTRUCTION
   167         *  @_nodoc
   168         *
   169         *  Section where `{@link #globals}` are placed.
   170         *
   171         *  All globals specified in the application configuration file
   172         *  are placed into this section.
   173         *
   174         *  The default is `null`, which means the `{@link #dataSection}` is used.
   175         */
   176        config String globalSection = null;
   177    
   178        /*!
   179         *  ======== sysStack ========
   180         *  The size of the executable's initial system stack
   181         *
   182         *  On architectures that maintain a separate "system stack" in addition
   183         *  to the normal `{@link #stack}`, this parameter sets its initial size
   184         *  (in units of chars).  This parameter is ignored for those
   185         *  architectures for which there is just a single stack; in other
   186         *  words, almost all known architectures.
   187         *
   188         *  This parameter is used on later generation TI/C55 16-bit DSPs where,
   189         *  in order to compatibly support 24-bit addresses, a separate
   190         *  system call/return stack that stores the upper address bits is
   191         *  employed.
   192         */
   193        config UInt sysStack = 0x1000;
   194    
   195        /*!
   196         *  ======== stack ========
   197         *  The size of the executable's initial stack
   198         *
   199         *  On platforms that enable control of the initial stack size (the
   200         *  stack that exists immediately after reset), this parameter specifies
   201         *  its initial size (in units of chars).
   202         */
   203        config UInt stack = 0x1000;
   204    
   205        /*!
   206         *  ======== heap ========
   207         *  The size of the executable's initial heap
   208         *
   209         *  On platforms that enable control of the size of the heap managed by
   210         *  the run-time support function malloc(), this parameter specifies
   211         *  its initial size (in units of chars).
   212         */
   213        config UInt heap = 0x1000;
   214    
   215        /*!
   216         *  ======== argSize ========
   217         *  The size allocated for command line args to the executable
   218         *
   219         *  On platforms that require static allocation of space to hold
   220         *  command line arguments, this parameter specifies its maximum size
   221         *  (in units of chars).
   222         *
   223         *  Command line arguments are passed to C's `main` function when it's
   224         *  declared via the prototype: `int main(int argc, char *argv[])`.  the
   225         *  `argv` array points to an array of strings allocated from the
   226         *  memory block whose size is controlled by `argSize`.
   227         *
   228         *  Setting `argSize` to 0 means that no `argv` array will be allocated
   229         *  and the application `main()` function should be declared as
   230         *  `int main(void)`.
   231         */
   232        config UInt argSize = 0x200;
   233    
   234        /*!
   235         *  ======== execCmd ========
   236         *  The command used to run this executable
   237         *
   238         *  This string is used to create a command that runs the executable
   239         *  from the command line.  If it is not set by the configuration script,
   240         *  it is set by the program's platform package (during program
   241         *  configuration).
   242         *
   243         *  This command is run as follows:
   244         *  @p(code)
   245         *      execCmd <prog> <args>
   246         *  @p
   247         *  where, `<prog>` is the name of the executable and `<args>` are
   248         *  the arguments specified in the test (if any).
   249         *
   250         *  @a(Note)
   251         *  This parameter is ignored if the exec command is specified as part
   252         *  of the test; see `{@link xdc.bld.Test#Attrs}`.
   253         */
   254        config String execCmd;
   255    
   256        /*!
   257         *  ======== linkTemplate ========
   258         *  The template for the Program's linker command file
   259         *
   260         *  A template is used to create the linker command file for each
   261         *  program.  It can be optionally specified by setting this
   262         *  configuration parameter in the program's configuration script.  If
   263         *  `linkTemplate` it is not set or set to `null`, the template is
   264         *  obtained from the platform associated with this program (i.e., the
   265         *  platform named by the `{@link #platform}` config in this module).
   266         *  See `{@link xdc.platform.IPlatform#getLinkTemplate IPlatform.getLinkTemplate}`.
   267         *
   268         *  The `linkTemplate` string names a package path relative path; e.g.,
   269         *  if the linker template you want to specify is
   270         *  `"templates/big_n_hairy.xdt"` in the package `myCompany.myPackage`,
   271         *  `linkTemplate` should be set to:
   272         *  @p(code)
   273         *      "myCompany/myPackage/templates/big_n_hairy.xdt"
   274         *  @p
   275         *  If `linkTemplate` begins with the string `"./"`, the file is NOT
   276         *  searched for along the package path; instead the file name is taken
   277         *  to specify a file relative to the current working directory.
   278         *
   279         *  In any case, if `linkTemplate` is non-`null`, the file must exist;
   280         *  otherwise, the configuration step will fail.
   281         *
   282         *  @see #sectionsTemplate, #sectionsExclude, #memoryExclude
   283         */
   284        config String linkTemplate = null;
   285    
   286        /*!
   287         *  ======== main ========
   288         *  The main entry point for the program
   289         *
   290         *  This parameter is optionally set by the user's program
   291         *  configuration script.  If it is not set, then a "legacy" `main()`
   292         *  function is assumed to be linked into the program; otherwise,
   293         *  the value of `main` is used as the "main" entry point to the
   294         *  program.
   295         */
   296        config Int (*main)(Int, Char*[]);
   297    
   298        /*!
   299         *  ======== sectMap ========
   300         *  A section name to SectionSpec mapping
   301         *
   302         *  This is a program specific mapping of output section names to
   303         *  {@link #SectionSpec} objects. The map supports mapping of section
   304         *  names to memory names; see {@link xdc.platform.IPlatform#sectMap}.
   305         *
   306         *  This parameter enables program configurations to place named
   307         *  sections in platform specific memory regions.  During generation of
   308         *  the linker command file, sections are mapped to named memories by
   309         *  first consulting this table; if the table does not contain a mapping,
   310         *  the target classifies each section as either "code", "data" or
   311         *  "stack" {@link xdc.bld.ITarget#sectMap} and the platform defines a
   312         *  memory region for each of these section types
   313         *  ({@link xdc.platform.IPlatform#codeMemory}/
   314         *  {@link xdc.platform.IPlatform#dataMemory}).  If
   315         *  this does not produce a result, an error is generated.
   316         *  It is important to note that `sectMap` does not contain the complete
   317         *  section allocation for the program. It only contains the entries
   318         *  explicitly added to `sectMap`. To get the complete section
   319         *  allocation, a user should call {@link #getSectMap}.
   320         *
   321         *  Suppose for example that the platform defines a memory segment
   322         *  named "DDR2".  The following configuration statement places
   323         *  everything from the ".text" section into the "DDR2" segment.
   324         *
   325         *  @p(code)
   326         *      Program.sectMap[".text"] = new Program.SectionSpec();
   327         *      Program.sectMap[".text"].loadSegment = "DDR2";
   328         *  @p
   329         *
   330         *  @see #SectionSpec
   331         *  @see xdc.platform.IPlatform#sectMap
   332         *  @see xdc.bld.ITarget#sectMap
   333         */
   334        config Any sectMap[string]; /* section name => SectionSpec */
   335    
   336        /*!
   337         *  ======== sectionsExclude ========
   338         *  Sections to exclude from linker command file generation
   339         *
   340         *  The `sectionsExclude` string is a JavaScript regular expression
   341         *  that is used to identify names of sections that should NOT be
   342         *  be handled by the normal linker command file generation process.
   343         *
   344         *  Sections whose name matches `sectionsExclude` must be handled
   345         *  using a custom linker command file or by specifying a custom template
   346         *  (see `{@link #sectionsTemplate}` or `{@link #linkTemplate}`).
   347         *  @a(Examples)
   348         *  To completely override the placement of all output sections you can
   349         *  define `sectionsExclude` to match any string.
   350         *  @p(code)
   351         *      // Note: the '.' below represents _any_ character, not just "."
   352         *      Program.sectionsExclude = ".*";
   353         *  @p
   354         *  To override output sections that begin with '.' you must specify
   355         *  the literal character '.' and use the '^' character to match the
   356         *  beginning of the string.
   357         *  @p(code)
   358         *      // the sequence '^\.' matches just "." at the start of the name
   359         *      Program.sectionsExclude = "^\.";
   360         *  @p
   361         *  To override a specific sections you should be careful to supply a
   362         *  regular expression that matches the entire section name.  You can
   363         *  use '$' to match the end of the name.
   364         *  @p(code)
   365         *      // match only ".const" or ".text"
   366         *      Program.sectionsExclude = "^\.const$|^\.text$";
   367         *  @p
   368         *
   369         *  @see #sectionsTemplate, #linkTemplate
   370         */
   371        config String sectionsExclude = null;
   372    
   373        /*!
   374         *  ======== memoryExclude ========
   375         *  @_nodoc
   376         *  Exclude memory definitions from linker command file generation
   377         *
   378         *  This parameter accepts boolean values. If true, it disables default
   379         *  memory definitions from being added to the generated linker command
   380         *  file.
   381         *
   382         *  This allows the user to define a custom memory map in a separate file
   383         *  and add it to the linker's command line.
   384         *
   385         *  The parameter was meant to be used only in certain generic platforms,
   386         *  but for now these platforms are not used.
   387         *
   388         *  @see #sectionsTemplate, #sectionsExclude, #linkTemplate
   389         */
   390        config Bool memoryExclude = false;
   391    
   392        /*!
   393         *  ======== sectionsTemplate ========
   394         *  Replace the sections portion of the generated linker command file
   395         *
   396         *  The `sectionsTemplate` string names a template that is used to replace
   397         *  the "`SECTIONS`" content to the generated linker command file.  This
   398         *  is useful especially when excluding specific sections via
   399         *  `{@link #sectionsExclude}` or when taking full control of the linker
   400         *  command file via `{@link #linkTemplate}` is unnecessary.  The original
   401         *  "`SECTIONS`" content is computed and passed as an argument to this
   402         *  template, which makes it relatively simple to perform small changes to
   403         *  the "`SECTIONS`" content without having to explicitly handle every
   404         *  section required by the compiler toolchain.
   405         *
   406         *  The `sectionsTemplate` string names a package path relative path; e.g.,
   407         *  if the linker template you want to specify is
   408         *  `"templates/mySections.xdt"` in the package `myCompany.myPackage`,
   409         *  `sectionsTemplate` should be set to:
   410         *  @p(code)
   411         *      "myCompany/myPackage/templates/mySections.xdt"
   412         *  @p
   413         *  If `sectionsTemplate` begins with the string `"./"`, the file is NOT
   414         *  searched for along the package path; instead the file name is taken
   415         *  to specify a file relative to the current working directory.
   416         *
   417         *  In any case, if `sectionsTemplate` is non-`null`, the file must exist;
   418         *  otherwise, the configuration step will fail.
   419         *
   420         *  During expansion of this template, there are three "parameters"
   421         *  that can be referenced to generate new content.
   422         *  @p(dlist)
   423         *      - `this`
   424         *          reference to the `{@link Program}` object
   425         *      - `$args[0]`
   426         *         is the complete section map derived from
   427         *         `{@link Program#sectMap}`; some special sections relevant to
   428         *         XDCtools are added to the map defined by `Program.sectMap`.
   429         *      - `$args[1]`
   430         *         is a string that contains the content that would have been
   431         *         placed in the `SECTIONS` portion of the generated linker
   432         *         command file.  This allows templates to easily modify this
   433         *         content or simply add statements before or after it.
   434         *  @p
   435         *  @a(Example)
   436         *  The following template, specific to TI compiler tools, adds start
   437         *  and size symbols for the `.stack` section and ensures that the stack
   438         *  is the first section to be allocated in its designated memory segment.
   439         *  @p(code)
   440         *    %// first output allocation for the .stack section
   441         *    %var sectMap = $args[0];
   442         *    %var stack = sectMap[".stack"];
   443         *       .stack: >`stack.loadSegment` START(_stack_start) SIZE(_stack_size)
   444         *    %
   445         *    %// now append the normally generated content
   446         *    `$args[1]`
   447         *  @p
   448         *  Note: this example requires that the `.stack` section be excluded
   449         *  from the normal generation via `{@link sectionsExclude}`; otherwise
   450         *  this section will be specified twice by the template shown above.
   451         *  @p(code)
   452         *      Program.sectionsExclude = "^\.stack$";
   453         *  @p
   454         *
   455         *  @see #sectionsExclude, #linkTemplate
   456         */
   457        config String sectionsTemplate = null;
   458    
   459        /*!
   460         *  ======== system ========
   461         *  @_nodoc
   462         *  A facade for the {@link xdc.runtime.System#SupportProxy} parameter
   463         *
   464         *  The program configuration script may select an implementation of
   465         *  the `xdc.runtime.ISystemSupport` interface and "bind" it by setting
   466         *  this parameter. If the module assigned to this parameter does not
   467         *  inherit from `xdc.runtime.ISystemSupport`, the configuration will fail.
   468         *
   469         *  If this parameter is not set (or set to `undefined`), then a default
   470         *  implementation is used: `xdc.runtime.SysStd` or, if
   471         *  `Program.build.target.os` is `null`, `xdc.runtime.SysMin`.  Recall that
   472         *  `Program.build.target.os` is specified in the Build Object Model;
   473         *  `Program.build.target` is the target specified when the executable was
   474         *  added to the package.
   475         *
   476         *  If this parameter is set to `null`, then the `System` module is not
   477         *  linked into the application (unless 'Memory' is used); any references
   478         *  to `System`'s methods will result in a linker error.  By setting this
   479         *  parameter to `null`, one is asserting that `System`'s methods will not
   480         *  be used.
   481         */
   482        config Any system;
   483    
   484        /*!
   485         *  ======== name ========
   486         *  The name of the executable file
   487         *
   488         *  This is the full file name (relative to the package's base) of the
   489         *  executable that results from this configuration.
   490         *
   491         *  @a(readonly)
   492         *  This parameter is set by the generated program configuration script
   493         *  and must not be modified.
   494         */
   495        config String name;
   496    
   497        /*!
   498         *  ======== cfgBase ========
   499         *  UNDER CONSTRUCTION
   500         *  @_nodoc
   501         */
   502        config String cfgBase;
   503    
   504        /*!
   505         *  ======== buildPackage ========
   506         *  The name of the executable's package
   507         *
   508         *  This is the full package name (relative to the package's repository)
   509         *  of the package that contains the executable being configured.
   510         *
   511         *  @a(readonly)
   512         *  This parameter is set by the generated program configuration script
   513         *  and must not be modified.
   514         */
   515        config String buildPackage;
   516    
   517        /*!
   518         *  ======== endian ========
   519         *  The endianess of the executable
   520         *
   521         *  This parameter is an alias for `build.target.model.dataModel` and is
   522         *  set to one of the following values: `"big"`, `"little"`, or `null`.
   523         *
   524         *  @a(readonly)
   525         *  This parameter is set by the generated program configuration script
   526         *  and must not be modified.
   527         */
   528        config String endian = null;
   529    
   530        /*!
   531         *  ======== codeModel ========
   532         *  The memory model for code
   533         *
   534         *  This parameter is an alias for `build.target.model.codeModel` and is
   535         *  set to one of the following target-specific values: `"near"`, `"far"`,
   536         *  `"large"`, or `null`.
   537         *
   538         *  @a(readonly)
   539         *  This parameter is set by the generated program configuration script
   540         *  and must not be modified.
   541         */
   542        config String codeModel = null;
   543    
   544        /*!
   545         *  ======== dataModel ========
   546         *  The memory model for data
   547         *
   548         *  This parameter is an alias for `build.target.model.dataModel` and is
   549         *  set to one of the following target-specific values: `"near"`, `"far"`,
   550         *  `"large"`, or `null`.
   551         *
   552         *  @a(readonly)
   553         *  This parameter is set by the generated program configuration script
   554         *  and must not be modified.
   555         */
   556        config String dataModel = null;
   557    
   558        /*!
   559         *  ======== build ========
   560         *  This program's build attributes
   561         *
   562         *  This parameter allows arbitrary build attributes to be carried
   563         *  forward from the Build Object Model (BOM) into the configuration
   564         *  model for program configuration scripts to read.
   565         *
   566         *  Conceptually, this config parameter should be declared as follows:
   567         *  @p(code)
   568         *      struct BuildAttrs inherits xdc.bld.Executable.Attrs {
   569         *          config xdc.bld.ITarget.Module target;
   570         *      };
   571         *  @p
   572         *  All parameters of the target associated with the executable being
   573         *  configured are available through '`Program.build.target`'. Any config
   574         *  parameter set in the BOM's `{@link xdc.bld.Executable#attrs}` is also
   575         *  available through `{@link #build}`.  For example, the name of the
   576         *  target is `Program.build.target.name` and the name of the
   577         *  executable's configuration script is `Program.build.cfgScript`.
   578         *
   579         *  @a(readonly)
   580         *  This parameter is set by the generated program configuration script
   581         *  and must not be modified.
   582         */
   583        config Any build;   /*  BuildAttrs */
   584    
   585        /*!
   586         *  ======== cpu ========
   587         *  The execution context "seen" by the executable.
   588         *
   589         *  Since the execution context is largely determined by the CPU that
   590         *  runs the executable, this configuration parameter allows scripts with
   591         *  access to the program object to conditionally configure based on CPU
   592         *  characteristics (e.g., ISA or revision of a chip).
   593         *
   594         *  @a(readonly)
   595         *  This parameter is set by the platform's implementation of
   596         *  `xdc.IPackage` (i.e., `package.xs`).
   597         */
   598        config xdc.platform.IExeContext.Instance cpu;
   599    
   600        /*!
   601         *  ======== platformName ========
   602         *  The name of the executable's platform
   603         *
   604         *  This field is the name of the platform instance used to create the
   605         *  executable; e.g., `"ti.platforms.sim55xx"`, or
   606         *  `"ti.platforms.sim6xxx:TMS320C6416"`.
   607         *
   608         *  Platform instance names have the form:
   609         *  @p(code)
   610         *      <platform_pkg>:<instance_id>
   611         *  @p
   612         *  where `<platform_pkg>` is the name of the platform package
   613         *  responsible for creating the platform instance and the optional
   614         *  "`:<instance_id>`" is a suffix that uniquely identifies the creation
   615         *  parameters for this instance.
   616         *
   617         *  The creation parameters are the values specified by the map
   618         *  `{@link xdc.bld.BuildEnvironment#platformTable}`;
   619         *  if this map does not contain the platform instance name, the
   620         *  instance is created with default values that are specific to the
   621         *  platform.
   622         *
   623         *  @a(readonly)
   624         *  This parameter is set by the generated program configuration script
   625         *  and must not be modified.
   626         */
   627        config String platformName;
   628    
   629        /*!
   630         *  ======== platform ========
   631         *  The executable's platform instance object
   632         *
   633         *  The platform instance that provided an execution context for the
   634         *  executable being configured.
   635         *
   636         *  @a(readonly)
   637         *  This parameter is set by the generated program configuration script
   638         *  and must not be modified.
   639         */
   640        config xdc.platform.IPlatform.Instance platform;
   641    
   642        /*!
   643         *  ======== global ========
   644         *  Global variable declarations
   645         *
   646         *  Assignments to this hash table become global symbols that can be
   647         *  used to directly reference objects.  These objects are declared
   648         *  in a generated header that is indirectly included by the header
   649         *  `xdc/cfg/global.h`.
   650         *
   651         *  Configuration scripts define symbols by adding new properties to
   652         *  `global`.
   653         *  @p(code)
   654         *      Program.global.myInstance = Mod.create();
   655         *      Program.global.myString = "hello world";
   656         *  @p
   657         *
   658         *  Programs can reference the symbols defined in `global` by including
   659         *  the C/C++ header `xdc/cfg/global.h` as follows:
   660         *  @p(code)
   661         *      #include <pkg/Mod.h>
   662         *      #include <xdc/cfg/global.h>
   663         *         :
   664         *      Mod_fxn(myInstance, ...);
   665         *      printf("greetings: %s\n", myString);
   666         *  @p
   667         *
   668         *  To compile sources that include `xdc/cfg/global.h`, one symbol must be
   669         *  defined before including this header:
   670         *  @p(dlist)
   671         *      - `xdc_cfg__header__`
   672         *          the package qualified name of the executable-specific C/C++
   673         *          header generated by the program configuration tool; e.g.,
   674         *          `local/examples/package/cfg/mycfg_x62.h`.
   675         *  @p
   676         *  For example, to compile sources that reference the values declared in
   677         *  `{@link #global}` for a TI C6x target with a generated
   678         *  configuration header named `package/cfg/mycfg_x62.h` in a package
   679         *  named `local.examples` the following command line is sufficient:
   680         *  @p(code)
   681         *      cl6x -Dxdc_cfg__header__=local/examples/package/cfg/mycfg_x62.h ...
   682         *  @p
   683         *
   684         *  The `xdc_cfg__header__` symbol is automatically defined when you use
   685         *  the the XDC Build Engine (`{@link xdc.bld}`) to create executables; see
   686         *  `{@link xdc.bld.Executable#addObjects}`
   687         *
   688         *  @see xdc.bld.Executable#addObjects
   689         */
   690        config Any global[string];
   691    
   692        /*!
   693         *  ======== symbol ========
   694         *  Global symbol specifications
   695         *
   696         *  UNDER CONSTRUCTION
   697         *  @_nodoc
   698         *
   699         *  This map contains symbol definitions that are used to define aliases
   700         *  or constants.  Symbol names are the C symbol names; i.e., compiler name
   701         *  mangling, such as the addition of a leading "_", is performed
   702         *  automatically.
   703         *
   704         *  @a(Examples)
   705         *  To define a symbolic constant:
   706         *  @p(code)
   707         *      Program.symbol["ONE"] = 1;
   708         *  @p
   709         *  The line above causes the symbol "ONE" to be defined in the linker
   710         *  command file to be equal to 1.  Note this in contrast to defining a
   711         *  variable whose value is 1; symbols do not occupy space, they are just
   712         *  symbolic constants defined in the symbol table of the executable.
   713         *
   714         *  This is currently used by xdc.runtime.Startup to define symbols
   715         *  optionally referenced by boot files that support early startup
   716         *  "reset" functions.
   717         */
   718        config Any symbol[string];
   719    
   720        /*!
   721         *  ======== exportModule ========
   722         *  Force all the symbols of a module to be part of a configuration
   723         *
   724         *  Although a call xdc.useModule() will force some of a module's methods
   725         *  to be part of a configuration, the linker is still free to omit any
   726         *  symbols that are not referenced.  Use of exportModule will force all
   727         *  methods of the specified module to be available.
   728         */
   729        Void exportModule(String modName);
   730    
   731        /*!
   732         *  ======== getSectMap ========
   733         *  Return the complete mapping of section names to `{@link #SectionSpec}`
   734         *  entries
   735         *
   736         *  The returned map is assembled from `{@link xdc.bld.ITarget#sectMap}`,
   737         *  `{@link xdc.platform.IPlatform#sectMap}`,
   738         *  `{@link xdc.platform.IPlatform#codeMemory}`,
   739         *  `{@link xdc.platform.IPlatform#dataMemory}`,
   740         *  `{@link xdc.platform.IPlatform#stackMemory}` and `{@link #sectMap}`.
   741         *  The function can be called at any time during configuration, but if
   742         *  it is called before all packages had a chance to change `sectMap`,
   743         *  the returned map may not correspond to the actual section
   744         *  allocation as configured in the linker command file.
   745         *
   746         *  @a(returns)
   747         *  `getSectMap` returns a map with section names as keys and
   748         *  `{@link #SectionSpec}` entries as values.
   749         */
   750        function getSectMap();
   751    
   752        /*!
   753         *  ======== importAssembly ========
   754         *  UNDER CONSTRUCTION
   755         *  @_nodoc
   756         */
   757        Void importAssembly(String asmName);
   758    
   759        /*!
   760         *  ======== targetModules ========
   761         *  UNDER CONSTRUCTION
   762         *  @_nodoc
   763         *
   764         *  This function returns a list of target modules. The list is completed
   765         *  only after all packages are closed, and runtime.finalized() is closed,
   766         *  so the only time when this function can be safely called is from
   767         *  within module$static$init and instance$static$init functions, package
   768         *  validate() functions, and templates.
   769         *
   770         *  This function is currently used by xdc.runtime modules to retrieve a
   771         *  list of modules that use xdc.runtime services. The list therefore does
   772         *  not include modules that have the attribute `@NoRuntime`.
   773         */
   774        function targetModules();
   775    }
   776    /*
   777     *  @(#) xdc.cfg; 1, 0, 2,0; 2-20-2019 10:21:59; /db/ztree/library/trees/xdc/xdc-F09/src/packages/
   778     */
   779