1    /*
     2     * Copyright (c) 2013-2015 Texas Instruments Incorporated - https://www.ti.com
     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    /*
    34     *  ======== Build.xdc ========
    35     *  metaonly module to support building various package/product libraries
    36     *
    37     */
    38    
    39    /*!
    40     *  ======== Build ========
    41     */
    42    
    43    @Template("./Build.xdt")
    44    metaonly module Build
    45    {
    46        /*!
    47         *  ======== LibType ========
    48         *  IPC library selection options
    49         *
    50         *  This enumeration defines all the IPC library types provided
    51         *  by the product. You can select the library type by setting
    52         *  the {@link #libType Build.libType} configuration parameter.
    53         *
    54         *  @field(LibType_Instrumented) The library supplied is prebuilt
    55         *  with logging and assertions enabled.
    56         *
    57         *  @field(LibType_NonInstrumented) The library supplied is prebuilt
    58         *  with logging and assertions disabled.
    59         *
    60         *  @field(LibType_Custom) This option builds the IPC library from
    61         *  sources using the options specified by {@link #customCCOpts}.
    62         *  Only the modules and APIs that your application uses are
    63         *  contained in the resulting executable. Program optimization is
    64         *  performed to reduce the size of the executable and improve
    65         *  performance. Enough debug information is retained to allow you
    66         *  to step through the application code in CCS and locate global
    67         *  variables.
    68         *
    69         *  @field(LibType_Debug) This option is similar to the LibType_Custom
    70         *  option in that it builds the IPC library from sources and omits
    71         *  modules and APIs that your code does not use. However, no program
    72         *  optimization is performed. The resulting executable is fully
    73         *  debuggable, and you can step into IPC code. The tradeoff is that
    74         *  the executable is larger and runs slower than builds that use the
    75         *  LibType_Custom option.
    76         *
    77         *  @field(LibType_PkgLib) This option uses the individual libraries
    78         *  built by each package of the IPC product. These libraries are
    79         *  not shipped. You must build the product to generate the package
    80         *  libraries. See the IPC Install Guides (links in the Release
    81         *  Note) for details on building the IPC product.
    82         *
    83         *  @see #libType
    84         */
    85        enum LibType {
    86            LibType_Instrumented,           /*! Instrumented */
    87            LibType_NonInstrumented,        /*! Non-instrumented */
    88            LibType_Custom,                 /*! Custom (Optimized) */
    89            LibType_Debug,                  /*! Custom (Debug) */
    90            LibType_PkgLib                  /*! Use package library */
    91        };
    92    
    93        /*!
    94         *  ======== libType ========
    95         *  IPC library type
    96         *
    97         *  The IPC runtime is provided in the form of a library that is
    98         *  linked with your application. Several forms of this library are
    99         *  provided with the IPC product. In addition, there is an option
   100         *  to build the library from source. This configuration parameter
   101         *  allows you to select the form of the IPC library to use.
   102         *
   103         *  The default value of libType is taken from the BIOS.libType
   104         *  configuration parameter. For a complete list of options and
   105         *  what they offer see {@link #LibType}.
   106         */
   107        config LibType libType;
   108    
   109        /*!
   110         *  ======== customCCOpts ========
   111         *  Compiler options used when building a custom IPC library
   112         *
   113         *  When {@link #libType Build.libType} is set to
   114         *  {@link #LibType_Custom Build_LibType_Custom} or
   115         *  {@link #LibType_Debug Build_LibType_Debug}, this string contains
   116         *  the options passed to the compiler during any re-build of the
   117         *  IPC sources.
   118         *
   119         *  In addition to the options specified by `Build.customCCOpts`,
   120         *  several `-D` and `-I` options are also passed to the compiler.
   121         *  The options specified by `Build.customCCOpts` preceed the `-D`
   122         *  and `-I` options passed to the compiler on the command line.
   123         *
   124         *  To view the custom compiler options, add the following line
   125         *  to your config script:
   126         *
   127         *  @p(code)
   128         *  print("Build.customCCOpts="+Build.customCCOpts);
   129         *  @p
   130         *
   131         *  When {@link #libType Build.libType} is set to
   132         *  {@link #LibType_Custom Build_LibType_Custom}, `Build.customCCOpts`
   133         *  is initialized to create a highly optimized library.
   134         *
   135         *  When {@link #libType Build.libType} is set to
   136         *  {@link #LibType_Debug Build_LibType_Debug}, `Build.customCCOpts`
   137         *  is initialized to create a non-optimized library that can be
   138         *  used to single-step through the APIs with the CCS debugger.
   139         *
   140         *  @a(Warning)
   141         *  The default value of `Build.customCCOpts`, which is derived from
   142         *  the target specified by your configuration, includes runtime
   143         *  model options (such as endianess) that must be the same for all
   144         *  sources built and linked into your application. You must not
   145         *  change or add any options that can alter the runtime model
   146         *  specified by the default value of `Build.customCCOpts`.
   147         */
   148        config String customCCOpts;
   149    
   150        /*!
   151         *  ======== assertsEnabled ========
   152         *  IPC assert checking in custom library enable flag
   153         *
   154         *  When set to true, assert checking code is compiled into
   155         *  the custom library created when {@link #libType Build.libType}
   156         *  is set to {@link #LibType_Custom Build_LibType_Custom} or
   157         *  {@link #LibType_Debug Build_LibType_Debug}.
   158         *
   159         *  When set to false, assert checking code is removed from the
   160         *  custom library created when Build.libType is set to
   161         *  Build.LibType_Custom or Build.LibType_Debug. This option can
   162         *  considerably improve runtime performance as well significantly
   163         *  reduce the application's code size.
   164         *
   165         *  @see #libType
   166         */
   167        config Bool assertsEnabled = true;
   168    
   169        /*!
   170         *  ======== logsEnabled ========
   171         *  IPC log support in custom library enable flag
   172         *
   173         *  When set to true, IPC execution log code is compiled into
   174         *  the custom library created when {@link #libType Build.libType}
   175         *  is set to {@link #LibType_Custom Build_LibType_Custom} or
   176         *  {@link #LibType_Debug Build_LibType_Debug}.
   177         *
   178         *  When set to false, all log code is removed from the custom
   179         *  library created when Build.libType = Build.LibType_Custom or
   180         *  Build.LibType_Debug. This option can considerably improve runtime
   181         *  performance as well signficantly reduce the application's code
   182         *  size.
   183         *
   184         *  @see #libType
   185         */
   186        config Bool logsEnabled = true;
   187    
   188        /*!
   189         *  ======== libDir ========
   190         */
   191        config String libDir = null;
   192    
   193        /*
   194         *  ======== getCCOpts ========
   195         *  Get the compiler options necessary to build
   196         */
   197        metaonly String getCCOpts(xdc.bld.ITarget.Module target);
   198    
   199        /*!
   200         *  ======== getDefaultCustomCCOpts ========
   201         */
   202        String getDefaultCustomCCOpts();
   203    
   204        /*!
   205         *  ======== getDefs ========
   206         *  Get the compiler -D options necessary to build
   207         */
   208        String getDefs();
   209    
   210        /*!
   211         *  ======== getCFiles ========
   212         *  Get the library C source files.
   213         */
   214        String getCFiles(String target);
   215    
   216        /*!
   217         *  ======== getAsmFiles ========
   218         *  Get the library Asm source files.
   219         */
   220        Any getAsmFiles(String target);
   221    
   222        /*
   223         *  ======== buildLibs ========
   224         *  This function generates the makefile goals for the libraries
   225         *  produced by a ti.sysbios package.
   226         */
   227        function buildLibs(objList, relList, filter, xdcArgs);
   228    
   229        /*!
   230         *  ======== getLibs ========
   231         *  Common getLibs() for all ipc packages.
   232         */
   233        function getLibs(pkg);
   234    }