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