1    /*
     2     * Copyright (c) 2016, Texas Instruments Incorporated
     3     * All rights reserved.
     4     *
     5     * Redistribution and use in source and binary forms, with or without
     6     * modification, are permitted provided that the following conditions
     7     * are met:
     8     *
     9     * *  Redistributions of source code must retain the above copyright
    10     *    notice, this list of conditions and the following disclaimer.
    11     *
    12     * *  Redistributions in binary form must reproduce the above copyright
    13     *    notice, this list of conditions and the following disclaimer in the
    14     *    documentation and/or other materials provided with the distribution.
    15     *
    16     * *  Neither the name of Texas Instruments Incorporated nor the names of
    17     *    its contributors may be used to endorse or promote products derived
    18     *    from this software without specific prior written permission.
    19     *
    20     * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    21     * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
    22     * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    23     * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
    24     * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    25     * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    26     * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
    27     * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
    28     * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
    29     * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
    30     * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    31     */
    32    
    33    requires xdc.platform [1,0,1];
    34    
    35    /*!
    36     *  ======== ti.platforms.generic ========
    37     *  Platform package for the generic platform.
    38     *
    39     *  This package implements the interfaces (xdc.platform.IPlatform)
    40     *  necessary to build and run executables on a "generic" platform; a
    41     *  platform specified by:
    42     *  @p(blist)
    43     *      - device name; e.g., "TMS320C2812"
    44     *      - catalog name; the name of a package containing the device named above
    45     *      - clock rate; the clock rate in MHz of the CPU
    46     *      - external memory map; an array of memory blocks external to the device
    47     *  @p
    48     *  For a complate list of parameters that can be specified when creating a
    49     *  platform instance see the instance configuration parameters specified
    50     *  by `{@link ti.platforms.generic.Platform}`.  This list, of course,
    51     *  includes all the instance config parameters specified by the
    52     *  `{@link xdc.platform.IPlatform}` interface.
    53     *
    54     *
    55     *  @a(Throws)
    56     *  `XDCException` exceptions are thrown for fatal errors. The following error
    57     *  codes are reported in the exception message:
    58     *  @p(dlist)
    59     *      -  `ti.platfoms.generic.LINK_TEMPLATE_ERROR`
    60     *           This error is raised when this platform cannot found the default
    61     *           linker command template `linkcmd.xdt` in the build target's
    62     *           package. When a target does not contain this file, the config
    63     *           parameter `{@link xdc.cfg.Program#linkTemplate}` must be set.
    64     *  @p
    65     *
    66     *  @a(EXAMPLES)
    67     *  Example 1: Suppose you need to create an application for a HW platform
    68     *  that uses the TMS320C2812 running at 150 MHz.  You can use this package
    69     *  (in lieu of one specifically created for the HW platform) by defining a
    70     *  named instance of this package's Platform module.  Add the following
    71     *  statements to your `config.bld` file to add the platform instance named
    72     *  "ti.platforms.generic:C28".
    73     *  @p(code)
    74     *      Build.platformTable["ti.platforms.generic:C28"] = {
    75     *          clockRate:   150,
    76     *          catalogName: "ti.catalog.c2800",
    77     *          deviceName:  "TMS320C2812"
    78     *      };
    79     *  @p
    80     *  With this name defined, it is now possible to configure an application
    81     *  using the platform instance name "ti.platforms.generic:C28".  For example,
    82     *  if you are using `{@link xdc.tools.configuro}` to configure your
    83     *  application, the string "ti.platforms.generic:C28" can now be used to
    84     *  identify your platform:
    85     *  @p(code)
    86     *      xs xdc.tools.configuro -b config.bld -p ti.platforms.generic:C28 ...
    87     *  @p
    88     *
    89     *  @p(html)
    90     *  <hr/>
    91     *  @p
    92     *
    93     *  Example 2: The following example illustrates how to specify a platform
    94     *  instance with memory regions external to the specified device.  In this
    95     *  case, we define a platform using a TMS320C6416 running at 600 MHz on a
    96     *  board with two external SDRAM memory blocks.
    97     *  @p(code)
    98     *      Build.platformTable["ti.platforms.generic:C64"] = {
    99     *          clockRate:          600,
   100     *          catalogName:        "ti.catalog.c6000",
   101     *          deviceName:         "TMS320C6416",
   102     *          externalMemoryMap : [
   103     *              ["SDRAM1", {
   104     *                  name: "SDRAM1",
   105     *                  base: 0x80000000, len: 0x1000000, space: "code/data"
   106     *              }],
   107     *              ["SDRAM2", {
   108     *                  name: "SDRAM2",
   109     *                  base: 0x90000000, len: 0x1000000, space: "code/data"
   110     *              }],
   111     *          ]
   112     *      }
   113     *  @p
   114     *
   115     *  The `externalMemoryMap` attribute is a map of string names to
   116     *  `{@link xdc.platform.IPlatform#Memory}` structures.
   117     *
   118     *  @see ti.platforms.generic.Platform
   119     *  @see xdc.bld.BuildEnvironment#platformTable
   120     *  @see xdc.platform.IPlatform
   121     */
   122    package ti.platforms.generic [1,0,0,1] {
   123        module Platform;
   124    }