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         *  @see #sectionsTemplate, #sectionsExclude, #memoryExclude
   280         */
   281        config String linkTemplate = null;
   282    
   283        /*!
   284         *  ======== main ========
   285         *  The main entry point for the program
   286         *
   287         *  This parameter is optionally set by the user's program
   288         *  configuration script.  If it is not set, then a "legacy" `main()`
   289         *  function is assumed to be linked into the program; otherwise,
   290         *  the value of `main` is used as the "main" entry point to the
   291         *  program.
   292         */
   293        config Int (*main)(Int, Char*[]);
   294    
   295        /*!
   296         *  ======== sectMap ========
   297         *  A section name to SectionSpec mapping
   298         *
   299         *  This is a program specific mapping of output section names to
   300         *  {@link #SectionSpec} objects. The map supports mapping of section
   301         *  names to memory names; see {@link xdc.platform.IPlatform#sectMap}.
   302         *
   303         *  This parameter enables program configurations to place named
   304         *  sections in platform specific memory regions.  During generation of
   305         *  the linker command file, sections are mapped to named memories by
   306         *  first consulting this table; if the table does not contain a mapping,
   307         *  the target classifies each section as either "code", "data" or
   308         *  "stack" {@link xdc.bld.ITarget#sectMap} and the platform defines a
   309         *  memory region for each of these section types
   310         *  ({@link xdc.platform.IPlatform#codeMemory}/
   311         *  {@link xdc.platform.IPlatform#dataMemory}).  If
   312         *  this does not produce a result, an error is generated.
   313         *  It is important to note that `sectMap` does not contain the complete
   314         *  section allocation for the program. It only contains the entries
   315         *  explicitly added to `sectMap`. To get the complete section
   316         *  allocation, a user should call {@link #getSectMap}.
   317         *
   318         *  Suppose for example that the platform defines a memory segment
   319         *  named "DDR2".  The following configuration statement places
   320         *  everything from the ".text" section into the "DDR2" segment.
   321         *
   322         *  @p(code)
   323         *      Program.sectMap[".text"] = new Program.SectionSpec();
   324         *      Program.sectMap[".text"].loadSegment = "DDR2";
   325         *  @p
   326         *
   327         *  @see #SectionSpec
   328         *  @see xdc.platform.IPlatform#sectMap
   329         *  @see xdc.bld.ITarget#sectMap
   330         */
   331        config Any sectMap[string]; /* section name => SectionSpec */
   332    
   333        /*!
   334         *  ======== sectionsExclude ========
   335         *  Sections to exclude from linker command file generation
   336         *
   337         *  The `sectionsExclude` string is a JavaScript regular expression
   338         *  that is used to identify names of sections that should NOT be
   339         *  be handled by the normal linker command file generation process.
   340         *
   341         *  Sections whose name matches `sectionsExclude` must be handled
   342         *  using a custom linker command file or by specifying a custom template
   343         *  (see `{@link #sectionsTemplate}` or `{@link #linkTemplate}`).
   344         *  @a(Examples)
   345         *  To completely override the placement of all output sections you can
   346         *  define `sectionsExclude` to match any string.
   347         *  @p(code)
   348         *      // Note: the '.' below represents _any_ character, not just "."
   349         *      Program.sectionsExclude = ".*";
   350         *  @p
   351         *  To override output sections that begin with '.' you must specify
   352         *  the literal character '.' and use the '^' character to match the
   353         *  beginning of the string.
   354         *  @p(code)
   355         *      // the sequence '^\.' matches just "." at the start of the name
   356         *      Program.sectionsExclude = "^\.";
   357         *  @p
   358         *  To override a specific sections you should be careful to supply a
   359         *  regular expression that matches the entire section name.  You can
   360         *  use '$' to match the end of the name.
   361         *  @p(code)
   362         *      // match only ".const" or ".text"
   363         *      Program.sectionsExclude = "^\.const$|^\.text$";
   364         *  @p
   365         *
   366         *  @see #sectionsTemplate, #linkTemplate
   367         */
   368        config String sectionsExclude = null;
   369    
   370        /*!
   371         *  ======== memoryExclude ========
   372         *  Exclude memory definitions from linker command file generation
   373         *
   374         *  This parameter accepts boolean values. If true, it disables default
   375         *  memory definitions from being added to the generated linker command
   376         *  file.
   377         *
   378         *  This allows the user to define a custom memory map in a separate file
   379         *  and add it to the linker's command line.
   380         *
   381         *  @see #sectionsTemplate, #sectionsExclude, #linkTemplate
   382         */
   383        config Bool memoryExclude = false;
   384    
   385        /*!
   386         *  ======== sectionsTemplate ========
   387         *  Replace the sections portion of the generated linker command file
   388         *
   389         *  The `sectionsTemplate` string names a template that is used to replace
   390         *  the "`SECTIONS`" content to the generated linker command file.  This
   391         *  is useful especially when excluding specific sections via
   392         *  `{@link #sectionsExclude}` or when taking full control of the linker
   393         *  command file via `{@link #linkTemplate}` is unnecessary.  The original
   394         *  "`SECTIONS`" content is computed and passed as an argument to this
   395         *  template, which makes it relatively simple to perform small changes to
   396         *  the "`SECTIONS`" content without having to explicitly handle every
   397         *  section required by the compiler toolchain.
   398         *
   399         *  The `sectionsTemplate` string names a package path relative path; e.g.,
   400         *  if the linker template you want to specify is
   401         *  `"templates/mySections.xdt"` in the package `myCompany.myPackage`,
   402         *  `sectionsTemplate` should be set to:
   403         *  @p(code)
   404         *      "myCompany/myPackage/templates/mySections.xdt"
   405         *  @p
   406         *  If `sectionsTemplate` begins with the string `"./"`, the file is NOT
   407         *  searched for along the package path; instead the file name is taken
   408         *  to specify a file relative to the current working directory.
   409         *
   410         *  In any case, if `sectionsTemplate` is non-`null`, the file must exist; 
   411         *  otherwise, the configuration step will fail.
   412         *
   413         *  During expansion of this template, there are three "parameters"
   414         *  that can be referenced to generate new content.
   415         *  @p(dlist)
   416         *      - `this`
   417         *          reference to the `{@link Program}` object
   418         *      - `$args[0]`
   419         *         is the complete section map derived from
   420         *         `{@link Program#sectMap}`; some special sections relevant to
   421         *         XDCtools are added to the map defined by `Program.sectMap`.
   422         *      - `$args[1]`
   423         *         is a string that contains the content that would have been
   424         *         placed in the `SECTIONS` portion of the generated linker
   425         *         command file.  This allows templates to easily modify this
   426         *         content or simply add statements before or after it.
   427         *  @p
   428         *  @a(Example)
   429         *  The following template, specific to TI compiler tools, adds start
   430         *  and size symbols for the `.stack` section and ensures that the stack
   431         *  is the first section to be allocated in its designated memory segment.
   432         *  @p(code)
   433         *    %// first output allocation for the .stack section
   434         *    %var sectMap = $args[0];
   435         *    %var stack = sectMap[".stack"];
   436         *       .stack: >`stack.loadSegment` START(_stack_start) SIZE(_stack_size)
   437         *    %
   438         *    %// now append the normally generated content
   439         *    `$args[1]`
   440         *  @p
   441         *  Note: this example requires that the `.stack` section be excluded
   442         *  from the normal generation via `{@link sectionsExclude}`; otherwise
   443         *  this section will be specified twice by the template shown above.
   444         *  @p(code)
   445         *      Program.sectionsExclude = "^\.stack$";
   446         *  @p
   447         *
   448         *  @see #sectionsExclude, #linkTemplate
   449         */
   450        config String sectionsTemplate = null;
   451    
   452        /*!
   453         *  ======== system ========
   454         *  @_nodoc
   455         *  A facade for the {@link xdc.runtime.System#SupportProxy} parameter
   456         *
   457         *  The program configuration script may select an implementation of
   458         *  the `xdc.runtime.ISystemSupport` interface and "bind" it by setting
   459         *  this parameter. If the module assigned to this parameter does not
   460         *  inherit from `xdc.runtime.ISystemSupport`, the configuration will fail.
   461         *
   462         *  If this parameter is not set (or set to `undefined`), then a default
   463         *  implementation is used: `xdc.runtime.SysStd` or, if
   464         *  `Program.build.target.os` is `null`, `xdc.runtime.SysMin`.  Recall that
   465         *  `Program.build.target.os` is specified in the Build Object Model;
   466         *  `Program.build.target` is the target specified when the executable was
   467         *  added to the package.
   468         *
   469         *  If this parameter is set to `null`, then the `System` module is not
   470         *  linked into the application (unless 'Memory' is used); any references
   471         *  to `System`'s methods will result in a linker error.  By setting this
   472         *  parameter to `null`, one is asserting that `System`'s methods will not 
   473         *  be used.
   474         */
   475        config Any system;
   476    
   477        /*!
   478         *  ======== name ========
   479         *  The name of the executable file
   480         *
   481         *  This is the full file name (relative to the package's base) of the
   482         *  executable that results from this configuration.
   483         *
   484         *  @a(readonly)
   485         *  This parameter is set by the generated program configuration script
   486         *  and must not be modified.
   487         */
   488        config String name;
   489    
   490        /*!
   491         *  ======== cfgBase ========
   492         *  UNDER CONSTRUCTION
   493         *  @_nodoc
   494         */
   495        config String cfgBase;
   496    
   497        /*!
   498         *  ======== buildPackage ========
   499         *  The name of the executable's package
   500         *
   501         *  This is the full package name (relative to the package's repository)
   502         *  of the package that contains the executable being configured.
   503         *
   504         *  @a(readonly)
   505         *  This parameter is set by the generated program configuration script
   506         *  and must not be modified.
   507         */
   508        config String buildPackage;
   509    
   510        /*!
   511         *  ======== endian ========
   512         *  The endianess of the executable
   513         *
   514         *  This parameter is an alias for `build.target.model.dataModel` and is
   515         *  set to one of the following values: `"big"`, `"little"`, or `null`.
   516         *
   517         *  @a(readonly)
   518         *  This parameter is set by the generated program configuration script
   519         *  and must not be modified.
   520         */
   521        config String endian = null;
   522    
   523        /*!
   524         *  ======== codeModel ========
   525         *  The memory model for code
   526         *
   527         *  This parameter is an alias for `build.target.model.codeModel` and is
   528         *  set to one of the following target-specific values: `"near"`, `"far"`,
   529         *  `"large"`, or `null`.
   530         *
   531         *  @a(readonly)
   532         *  This parameter is set by the generated program configuration script
   533         *  and must not be modified.
   534         */
   535        config String codeModel = null;
   536    
   537        /*!
   538         *  ======== dataModel ========
   539         *  The memory model for data
   540         *
   541         *  This parameter is an alias for `build.target.model.dataModel` and is
   542         *  set to one of the following target-specific values: `"near"`, `"far"`,
   543         *  `"large"`, or `null`.
   544         *
   545         *  @a(readonly)
   546         *  This parameter is set by the generated program configuration script
   547         *  and must not be modified.
   548         */
   549        config String dataModel = null;
   550    
   551        /*!
   552         *  ======== build ========
   553         *  This program's build attributes
   554         *
   555         *  This parameter allows arbitrary build attributes to be carried
   556         *  forward from the Build Object Model (BOM) into the configuration
   557         *  model for program configuration scripts to read.
   558         *
   559         *  Conceptually, this config parameter should be declared as follows:
   560         *  @p(code)
   561         *      struct BuildAttrs inherits xdc.bld.Executable.Attrs {
   562         *          config xdc.bld.ITarget.Module target;
   563         *      };
   564         *  @p
   565         *  All parameters of the target associated with the executable being
   566         *  configured are available through '`Program.build.target`'. Any config
   567         *  parameter set in the BOM's `{@link xdc.bld.Executable#attrs}` is also
   568         *  available through `{@link #build}`.  For example, the name of the
   569         *  target is `Program.build.target.name` and the name of the
   570         *  executable's configuration script is `Program.build.cfgScript`.
   571         *
   572         *  @a(readonly)
   573         *  This parameter is set by the generated program configuration script
   574         *  and must not be modified.
   575         */
   576        config Any build;   /*  BuildAttrs */
   577    
   578        /*!
   579         *  ======== cpu ========
   580         *  The execution context "seen" by the executable.
   581         *
   582         *  Since the execution context is largely determined by the CPU that
   583         *  runs the executable, this configuration parameter allows scripts with
   584         *  access to the program object to conditionally configure based on CPU
   585         *  characteristics (e.g., ISA or revision of a chip).
   586         *
   587         *  @a(readonly)
   588         *  This parameter is set by the platform's implementation of
   589         *  `xdc.IPackage` (i.e., `package.xs`).
   590         */
   591        config xdc.platform.IExeContext.Instance cpu;
   592    
   593        /*!
   594         *  ======== platformName ========
   595         *  The name of the executable's platform
   596         *
   597         *  This field is the name of the platform instance used to create the
   598         *  executable; e.g., `"ti.platforms.sim55xx"`, or
   599         *  `"ti.platforms.sim6xxx:TMS320C6416"`.
   600         *
   601         *  Platform instance names have the form:
   602         *  @p(code)
   603         *      <platform_pkg>:<instance_id>
   604         *  @p
   605         *  where `<platform_pkg>` is the name of the platform package 
   606         *  responsible for creating the platform instance and the optional
   607         *  "`:<instance_id>`" is a suffix that uniquely identifies the creation
   608         *  parameters for this instance.
   609         *
   610         *  The creation parameters are the values specified by the map
   611         *  `{@link xdc.bld.BuildEnvironment#platformTable}`;
   612         *  if this map does not contain the platform instance name, the
   613         *  instance is created with default values that are specific to the
   614         *  platform.
   615         *
   616         *  @a(readonly)
   617         *  This parameter is set by the generated program configuration script
   618         *  and must not be modified.
   619         */
   620        config String platformName;
   621    
   622        /*!
   623         *  ======== platform ========
   624         *  The executable's platform instance object
   625         *
   626         *  The platform instance that provided an execution context for the
   627         *  executable being configured.
   628         *
   629         *  @a(readonly)
   630         *  This parameter is set by the generated program configuration script
   631         *  and must not be modified.
   632         */
   633        config xdc.platform.IPlatform.Instance platform;
   634    
   635        /*!
   636         *  ======== global ========
   637         *  Global variable declarations
   638         *
   639         *  Assignments to this hash table become global symbols that can be
   640         *  used to directly reference objects.  These objects are declared
   641         *  in a generated header that is indirectly included by the header
   642         *  `xdc/cfg/global.h`.
   643         *
   644         *  Configuration scripts define symbols by adding new properties to
   645         *  `global`.
   646         *  @p(code)
   647         *      Program.global.myInstance = Mod.create();
   648         *      Program.global.myString = "hello world";
   649         *  @p
   650         *
   651         *  Programs can reference the symbols defined in `global` by including
   652         *  the C/C++ header `xdc/cfg/global.h` as follows:
   653         *  @p(code)
   654         *      #include <pkg/Mod.h>
   655         *      #include <xdc/cfg/global.h>
   656         *         :
   657         *      Mod_fxn(myInstance, ...);
   658         *      printf("greetings: %s\n", myString);
   659         *  @p
   660         *
   661         *  To compile sources that include `xdc/cfg/global.h`, one symbol must be
   662         *  defined before including this header:
   663         *  @p(dlist)
   664         *      - `xdc_cfg__header__`
   665         *          the package qualified name of the executable-specific C/C++
   666         *          header generated by the program configuration tool; e.g.,
   667         *          `local/examples/package/cfg/mycfg_x62.h`.
   668         *  @p
   669         *  For example, to compile sources that reference the values declared in
   670         *  `{@link #global}` for a TI C6x target with a generated
   671         *  configuration header named `package/cfg/mycfg_x62.h` in a package
   672         *  named `local.examples` the following command line is sufficient:
   673         *  @p(code)
   674         *      cl6x -Dxdc_cfg__header__=local/examples/package/cfg/mycfg_x62.h ...
   675         *  @p
   676         *
   677         *  The `xdc_cfg__header__` symbol is automatically defined when you use
   678         *  the the XDC Build Engine (`{@link xdc.bld}`) to create executables; see
   679         *  `{@link xdc.bld.Executable#addObjects}`
   680         *
   681         *  @see xdc.bld.Executable#addObjects
   682         */
   683        config Any global[string];
   684    
   685        /*!
   686         *  ======== symbol ========
   687         *  Global symbol specifications
   688         *
   689         *  UNDER CONSTRUCTION
   690         *  @_nodoc
   691         *
   692         *  This map contains symbol definitions that are used to define aliases
   693         *  or constants.  Symbol names are the C symbol names; i.e., compiler name
   694         *  mangling, such as the addition of a leading "_", is performed
   695         *  automatically.
   696         *
   697         *  @a(Examples)
   698         *  To define a symbolic constant:
   699         *  @p(code)
   700         *      Program.symbol["ONE"] = 1;
   701         *  @p
   702         *  The line above causes the symbol "ONE" to be defined in the linker
   703         *  command file to be equal to 1.  Note this in contrast to defining a
   704         *  variable whose value is 1; symbols do not occupy space, they are just
   705         *  symbolic constants defined in the symbol table of the executable.
   706         *
   707         *  This is currently used by xdc.runtime.Startup to define symbols
   708         *  optionally referenced by boot files that support early startup
   709         *  "reset" functions.
   710         */
   711        config Any symbol[string];
   712    
   713        /*!
   714         *  ======== exportModule ========
   715         *  Force all the symbols of a module to be part of a configuration
   716         *
   717         *  Although a call xdc.useModule() will force some of a module's methods
   718         *  to be part of a configuration, the linker is still free to omit any
   719         *  symbols that are not referenced.  Use of exportModule will force all
   720         *  methods of the specified module to be available.
   721         */
   722        Void exportModule(String modName);
   723    
   724        /*!
   725         *  ======== getSectMap ========
   726         *  Return the complete mapping of section names to `{@link #SectionSpec}`
   727         *  entries
   728         *
   729         *  The returned map is assembled from `{@link xdc.bld.ITarget#sectMap}`,
   730         *  `{@link xdc.platform.IPlatform#sectMap}`,
   731         *  `{@link xdc.platform.IPlatform#codeMemory}`,
   732         *  `{@link xdc.platform.IPlatform#dataMemory}`,
   733         *  `{@link xdc.platform.IPlatform#stackMemory}` and `{@link #sectMap}`.
   734         *  The function can be called at any time during configuration, but if
   735         *  it is called before all packages had a chance to change `sectMap`,
   736         *  the returned map may not correspond to the actual section
   737         *  allocation as configured in the linker command file.
   738         *
   739         *  @a(returns)
   740         *  `getSectMap` returns a map with section names as keys and
   741         *  `{@link #SectionSpec}` entries as values.
   742         */
   743        function getSectMap();
   744    
   745        /*!
   746         *  ======== importAssembly ========
   747         *  UNDER CONSTRUCTION
   748         *  @_nodoc
   749         */
   750        Void importAssembly(String asmName);
   751    
   752        /*!
   753         *  ======== targetModules ========
   754         *  UNDER CONSTRUCTION
   755         *  @_nodoc
   756         *
   757         *  This function returns a list of target modules. The list is completed
   758         *  only after all packages are closed, and runtime.finalized() is closed,
   759         *  so the only time when this function can be safely called is from
   760         *  within module$static$init and instance$static$init functions, package
   761         *  validate() functions, and templates.
   762         *
   763         *  This function is currently used by xdc.runtime modules to retrieve a
   764         *  list of modules that use xdc.runtime services. The list therefore does
   765         *  not include modules that have the attribute `@NoRuntime`.
   766         */
   767        function targetModules();
   768    
   769        /*!
   770         *  ======== freezeRomConfig ========
   771         *  UNDER CONSTRUCTION
   772         *  @_nodoc
   773         */
   774        Void freezeRomConfig(String modName, String cfgName);
   775    
   776        /*!
   777         *  ======== freezeRomConfig2 ========
   778         *  UNDER CONSTRUCTION
   779         *  @_nodoc
   780         */
   781        function freezeRomConfig2(mod, cfgName);
   782    
   783        /*!
   784         *  ======== freezeRomParams ========
   785         *  UNDER CONSTRUCTION
   786         *  @_nodoc
   787         */
   788        function freezeRomParams(mod);
   789    
   790        /*!
   791         *  ======== frozenRomConfig ========
   792         *  UNDER CONSTRUCTION
   793         *  @_nodoc
   794         */
   795        Bool frozenRomConfig(String modName, String cfgName);
   796    
   797        /*!
   798         *  ======== frozenRomConfig2 ========
   799         *  UNDER CONSTRUCTION
   800         *  @_nodoc
   801         */
   802        function frozenRomConfig2(mod, cfgName);
   803    }
   804    /*
   805     *  @(#) xdc.cfg; 1, 0, 2,472; 3-20-2014 17:05:21; /db/ztree/library/trees/xdc/xdc-A32x/src/packages/
   806     */
   807