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     *  ======== IPlatform.xdc ========
    14     */
    15    
    16    package xdc.platform;
    17    
    18    /*!
    19     *  ======== IPlatform ========
    20     *  Configuration-time interface to all platforms.
    21     *
    22     *  This interface defines the elements that must be implemented by all
    23     *  "platform packages".  All programs are built to execute on a platform
    24     *  and each program includes exactly one platform package (which defines
    25     *  the platform).
    26     *
    27     *  Platform packages contain exactly one module named "Platform" which
    28     *  implements the `xdc.platform.IPlatform` interface defined here.
    29     *
    30     *  Program configuration scripts may read (but not modify) the attributes
    31     *  provided by this interface from the global `Program` object; see
    32     *  `{@link xdc.cfg.Program#platform}`.
    33     */
    34    metaonly interface IPlatform
    35    {
    36        /*!
    37         *  ======== Board ========
    38         *  Board-level description.
    39         */
    40        struct Board {
    41            string   id;            /*! unique id within the platform */
    42            string   boardName;     /*! name of the board */
    43            string   boardFamily;   /*! optional family name */
    44            string   boardRevision; /*! optional revision string */
    45        };
    46    
    47        /*!
    48         *  ======== Memory ========
    49         *  A named contiguous range of addresses.
    50         *
    51         *  Memory structures are used in the description of the memory available
    52         *  from CPUs and platforms.
    53         */
    54        struct Memory {
    55            string      comment;    /*! description of this block */
    56            string      name;       /*! name of memory segment */
    57            string      space;      /*! "code", "data", "code/data", etc.... */
    58            unsigned    page;       /*! page of memory segment */
    59            unsigned    base;       /*! base address of memory segment */
    60            unsigned    len;        /*! length of memory segment */
    61            string      access;     /*! attributes of memory: "RWX" */
    62            Bool        cacheable;  /*! Is this block cacheable? */
    63            Any         cacheAttrs; /*! Device specific MMU attributes */
    64        };
    65    
    66        /*! Type to be used for maps of Memory objects */
    67        typedef Memory MemoryMap[string];
    68    
    69    instance:
    70        /*!
    71         *  ======== create ========
    72         *  Constructor for IPlatform instances.
    73         *
    74         *  @param(name)    the name of the platform instance being created
    75         *
    76         *                  This name is the suffix of the platform
    77         *                  specification supplied in the build script after
    78         *                  the platform name (and optional ':') prefix has
    79         *                  been removed.  So the platform instance name
    80         *                  "joes.platform.foo:bar" results in the name "bar"
    81         *                  and the name "joes.platform.foo" result in the name
    82         *                  "".
    83         */
    84        create(string name);
    85        
    86        /*
    87         *  ======== memTab ========
    88         *  A mapping of memory names to external memory objects.
    89         *
    90         *  This hash table is used to map linker memory region names ("EPROG",
    91         *  "EDATA", etc.) to `{@link xdc.platform.IPlatform#Memory}` objects.
    92         *  During generation of linker command files, for example, this table
    93         *  may be used to genenerate physical memory map declarations.
    94         *
    95         *  Platforms with a fixed memory map can initialize this table
    96         *  "statically" in Platform.xdc using the following syntax:
    97         *  @p(code)
    98         *      override config xdc.platform.IPlatform.Memory memTab[string] = [
    99         *          ["PMEM", {name: "PMEM", base: 0x00000200, len: 0x0000FE00}],
   100         *              :
   101         *      ];
   102         *  @p
   103         *  Alternatively, platforms can initialize this table dynamically in
   104         *  the platform package's `init()` function (see `{@link xdc.IPackage}`)
   105         *  using the following syntax:
   106         *  @p(code)
   107         *    function init()
   108         *    {
   109         *              :
   110         *        this.memTab["PMEM"] = {name: "PMEM", base: 0x200, len: 0xFE00};
   111         *              :
   112         *    }
   113         *  @p
   114         *  @a(readonly)   this parameter is set by the platform and read by
   115         *              program configuration scripts.
   116         */
   117    //    config Memory memTab[string];     /* memory name => memory object */
   118    
   119        /*!
   120         *  ======== externalMemoryMap ========
   121         *  A mapping of memory names to memory objects for external memory.
   122         *
   123         *  This parameter defines the external portion of the platform's memory
   124         *  map.
   125         */
   126        readonly config xdc.platform.IPlatform.Memory externalMemoryMap[string];
   127    
   128        /*!
   129         *  ======== customMemoryMap ========
   130         *  A custom mapping of memory names to memory objects.
   131         *
   132         *  This parameter allows platform instances to completely overwrite a 
   133         *  default memory map based on the internal memory map coming from CPU's
   134         *  memory map and externalMemoryMap.
   135         *
   136         *  Custom memory map must fit within the default memory map, unless the
   137         *  verification of the fit is disabled (see `{@link xdc.platform}`). 
   138         */
   139        config xdc.platform.IPlatform.Memory customMemoryMap[string];
   140    
   141        /*!
   142         *  ======== renameMap ========
   143         *  A map for renaming memory objects.
   144         *
   145         *  This map renames memory objects. If you do not want to change
   146         *  addresses in the default memory map, but you only want to rename the
   147         *  existing memory objects, you should use this parameter.
   148         *
   149         *  This map and `customMemoryMap` should not be used together because this
   150         *  map renames the default memory, but then `customMemoryMap` replaces the
   151         *  default memory objects. The parameters `codeMemory`, `dataMemory` and
   152         *  `stackMemory` are not automatically reassigned to new names. It is the
   153         *  user's responsibility to set those parameters accordingly to 
   154         *  `renameMap`.
   155         */
   156        config string renameMap[string];
   157    
   158        /*!
   159         *  ======== dataMemory ========
   160         *  The default segment for data sections.
   161         *
   162         *  Each target has a section map with keys equal to the names of all
   163         *  sections that compiler and assembler for that target generate. The
   164         *  value for each key is either "code" or "data" or "stack". A linker
   165         *  template reads that map and puts all "data" sections in the segment
   166         *  defined by this configuration parameter.
   167         *
   168         *  @see #codeMemory
   169         *  @see #stackMemory
   170         */
   171        config string dataMemory;
   172    
   173        /*!
   174         *  ======== codeMemory ========
   175         *  The default segment for code sections.
   176         *
   177         *  Each target has a section map with keys equal to the names of all
   178         *  sections that compiler and assembler for that target generate. The
   179         *  value for each key is either "code" or "data" or "stack". A linker
   180         *  template reads that map and puts all "code" sections in the segment
   181         *  defined by this configuration parameter.
   182         *
   183         *  @see #dataMemory
   184         *  @see #stackMemory
   185         */
   186        config string codeMemory;
   187    
   188        /*!
   189         *  ======== stackMemory ========
   190         *  The default segment for stack.
   191         *
   192         *  Each target has a section map with keys equal to the names of all
   193         *  sections that compiler and assembler for that target generate. The
   194         *  value for each key is either "code" or "data" or "stack". A linker
   195         *  template reads that map and puts all "stack" sections in the segment
   196         *  defined by this configuration parameter.
   197         *
   198         *  @see #dataMemory
   199         *  @see #codeMemory
   200         */
   201        config string stackMemory;
   202    
   203        /*!
   204         *  ======== sectMap ========
   205         *  A mapping of linker output section names to memory segments.
   206         *
   207         *  During the generation of linker command files, the templates used to
   208         *  create these files examine several sources of information to determine 
   209         *  the placement of named output sections into memory segments defined
   210         *  by the platform.  The default placement, described below,
   211         *  uses information from the target and this platform's
   212         *  `{@link #codeMemory}`, `{@link #dataMemory}`, and
   213         *  `{@link #stackMemory}` configuration parameters.
   214         *
   215         *  `sectMap` is used to override this default placement of
   216         *  output sections (".text", ".cinit", etc.) to a memory 
   217         *  segment defined by the platform's memory map.  For example, even if
   218         *  a platform's `codeMemory` parameter is defined to be "SRAM" and
   219         *  ".cinit" output sections are "code" sections, if the platform also
   220         *  defines the following `sectMap`, the section ".cinit" will be placed
   221         *  into a memory segment named "DDR2".
   222         *  @p(code)
   223         *      sectMap[] = [
   224         *          [".cinit", "DDR2"],
   225         *      ];
   226         *  @p
   227         *
   228         *  @a(Note) If an output section has an entry in
   229         *  `{@link xdc.cfg.Program#sectMap Program.sectMap}`, that entry
   230         *  overrides the placement specified by this `sectMap`.  A program's
   231         *  `sectMap` configuration always overrides the platform's `sectMap`
   232         *  settings.
   233         *
   234         *  @a(Default Mapping)
   235         *  The default placement of a target's output sections into memory
   236         *  segments defined by the platform is determined by the following
   237         *  configuration parameters:
   238         *  @p(blist)
   239         *      - `{@link xdc.bld.ITarget#sectMap ITarget.sectMap}`
   240         *          used to map a named output section to either "code", "data",
   241         *          or "stack"
   242         *      - `{@link #codeMemory}`
   243         *          names a memory segment that will contain all "code"
   244         *          output sections
   245         *      - `{@link #dataMemory}`
   246         *          names a memory segment that will contain all "data"
   247         *          output sections
   248         *      - `{@link #stackMemory}`
   249         *          names a memory segment that will contain all "stack"
   250         *          output sections
   251         *  @p
   252         *
   253         *  @see xdc.cfg.Program#sectMap
   254         *  @see xdc.bld.ITarget#sectMap
   255         */
   256        config string sectMap[string]; /* section name => memory segment */
   257        
   258        /*!
   259         *  ======== peripherals ========
   260         *  @_nodoc
   261         *
   262         *  A map of peripherals available on a platform instance
   263         *
   264         *  The map contains peripherals from an 
   265         *  `{@link xdc.platform.ICpuDataSheet}` instance available as
   266         *  `{@link xdc.cfg.Program#cpu.attrs}`, and peripherals defined in this
   267         *  platform instance. The map is initialized by the platform instance,
   268         *  and in multicore platforms the instance must add only peripherals
   269         *  available to the CPU for which an executable is being built.
   270         */
   271        config IPeripheral.Instance peripherals[string];
   272        
   273        /*!
   274         *  ======== getCpuDataSheet ========
   275         *  Get the Cpu data sheet object corresponding to specified cpu id.
   276         *
   277         *  This function executes in either the Configuration object model
   278         *  or the Build object model.
   279         *
   280         *  @param(cpuId)   a string that corresponds to the platform-specific id
   281         *                  of a CPU on this platform that runs executables.
   282         *
   283         *  @a(returns)     Returns an `{@link xdc.platform.ICpuDataSheet}`
   284         *                  instance object that corresponds to the specified
   285         *                  cpuId.
   286         *
   287         *  @a(throws)      `Error` exceptions are thrown for fatal errors.
   288         */
   289        function getCpuDataSheet(cpuId);
   290    //    xdc.platform.ICpuDataSheet.Instance getCpuDataSheet(string cpuId);
   291    
   292        /*!
   293         *  ======== getCreateArgs ========
   294         *  DEPRECATED
   295         *  @_nodoc
   296         *
   297         *  Get the value of the args parameter used to create this instance
   298         *
   299         *  This function executes in either the Configuration object model
   300         *  or the Build object model.
   301         *
   302         *  @a(returns)     Returns the "args" object that passed to this
   303         *                  module's create method when the instance was created.
   304         *
   305         *  @a(throws)      `Error` exceptions are thrown for fatal errors.
   306         */
   307        function getCreateArgs();
   308    // any getCreateArgs();
   309        
   310        /*!
   311         *  ======== getExeContext ========
   312         *  Get execution context object corresponding to the specified program.
   313         *
   314         *  This is called before the program's configuration script runs to 
   315         *  get the Cpu object that is assigned to the program's cpu field.
   316         *
   317         *  Note: that the build script for the program is responsible for
   318         *  specifying the CPU; this is done by either implicitly naming the
   319         *  platform or explicitly naming a particular CPU on the platform
   320         *  (see `{@link xdc.bld.Executable#Attrs.cpuId}`).
   321         *
   322         *  This function executes in the Configuration object model.
   323         *
   324         *  @param(prog)    the `{@link xdc.cfg.Program}` object representing the
   325         *                  program being configured.
   326         *
   327         *                  This object contains the following properties that
   328         *                  allows the platform to determine the appropriate Cpu
   329         *                  object to return (if there is more than one):
   330         *                      `prog.build.cpuId`,
   331         *                      `prog.build.cpuArgs`, 
   332         *                      `prog.build.target`,
   333         *
   334         *  @a(returns)     Returns an `{@link xdc.platform.IExeContext}` instance
   335         *                  object that corresponds to the CPU that will run the
   336         *                  specified program.
   337         *
   338         *  @a(throws)      `Error` exceptions are thrown for fatal errors.
   339         */
   340        function getExeContext(prog);
   341    //    xdc.platform.IExeContext.Instance getExeContext(xdc.cfg.Program.Module prog);
   342    
   343        /*!
   344         *  ======== getExecCmd ========
   345         *  Get the exec command used to run the program on this platform.  
   346         *
   347         *  This function is called after the program's configuration script runs
   348         *  and returns commands that are used to load and run the specified
   349         *  program.  These commands are placed in a makefile that is included
   350         *  by the client package's generated makefile.  Thus, the commands may
   351         *  refer to macros defined in this environment; e.g., `$(SHELL)` and
   352         *  `$(XDCROOT)`, etc.
   353         *
   354         *  The special macro `$(1)` expands to test-specific arguments
   355         *  (`{@link xdc.bld.Test#attrs.execArgs}`) that are passed from the test
   356         *  to the platform's exec command.  Thus, all platforms that support
   357         *  arguments to their exec command, should embed "`$(1)`" within the
   358         *  command string at the appropriate place to have these arguments
   359         *  interpreted by the exec command.
   360         *
   361         *  For example, a platform that uses a shell script to run executables
   362         *  and allows options to be passed to the shell script might return
   363         *  the following string:
   364         *  @p(code)
   365         *      "$(SHELL) <exec_path> $(1) <exe_name>"
   366         *  @p
   367         *  where, `<exec_path>` is the absolute path to the platform's exec
   368         *  shell script, and `<prog_name>` is the name of the executable relative
   369         *  to the package's base directory (i.e., `{@link xdc.cfg.Program#name}`).
   370         *
   371         *  This function executes in the Configuration object model.
   372         *
   373         *  @param(prog)    the `{@link xdc.cfg.Program}` object representing the
   374         *                  program being configured.
   375         *
   376         *                  This object contains the following properties that
   377         *                  allows the platform to determine the appropriate Cpu
   378         *                  object to return (if there is more than one):
   379         *                      `prog.build.cpuId`,
   380         *                      `prog.build.cpuArgs`,
   381         *                      `prog.build.target`
   382         *
   383         *  @param(platPath) full path to the platform package for the program
   384         *
   385         *  @a(returns)     Returns a string of commands used to execute this
   386         *                  program in the context of the XDC generated makefiles.
   387         *                  
   388         *  @a(throws)      `Error` exceptions are thrown for fatal errors.
   389         */
   390        function getExecCmd(prog, platPath);
   391    //    string  getExecCmd(xdc.cfg.Program.Module prog, string platPath);
   392    
   393        /*!
   394         *  ======== getLinkTemplate ========
   395         *  Get Linker Command file template used to link an executable.
   396         *
   397         *  In the event that no template is provided by the program
   398         *  configuration script (see `{@link xdc.cfg.Program#linkTemplate}`), 
   399         *  the template file identified by this method is used to generate the
   400         *  linker command file used to create the executable.
   401         *
   402         *  This function executes in the Configuration object model and
   403         *  is called after the program configuration script runs.  The template
   404         *  is expanded in the context of the Configuration Object Model.  
   405         *
   406         *  @param(prog)    the `{@link xdc.cfg.Program}` object representing the
   407         *                  program being configured.
   408         *
   409         *                  This object contains the following properties that
   410         *                  allows the platform to determine the appropriate link
   411         *                  template to return:
   412         *                  @p(blist)
   413         *                      - `prog.build.cpuId`,
   414         *                      - `prog.build.cpuArgs`,
   415         *                      - `prog.build.target`
   416         *                  @p
   417         *  @a(returns)     Returns a path string to a template file or `null`.  If
   418         *                  `null`, no linker command file is generated; otherwise
   419         *                  this path is relative to the package path.
   420         *                  
   421         *  @a(throws)      `Error` exceptions are thrown for fatal errors.
   422         */
   423        function getLinkTemplate(prog);
   424    //    string getLinkTemplate(prog);
   425    }
   426    /*
   427     *  @(#) xdc.platform; 1, 0, 1,472; 3-20-2014 17:05:25; /db/ztree/library/trees/xdc/xdc-A32x/src/packages/
   428     */
   429