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