1    /*
     2     * Copyright (c) 2013, 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     *  ======== SemiHostSupport.xdc ========
    34     */
    35    
    36    package ti.sysbios.rts.gnu;
    37    
    38    /*!
    39     *  ======== SemiHostSupport ========
    40     *  This module does the required setup for supporting Semi-Hosted SYS/BIOS
    41     *  applications for all Cortex-A and Cortex-M GNU targets.
    42     *
    43     *  For Cortex-A targets, this module generates a SVC_Handler() function and
    44     *  registers it as the default SWI/SVC handler.
    45     *
    46     *  This module also registers a startup last function
    47     *  (see {@link xdc.runtime.Startup#lastFxns Startup.lastFxns}) that initializes
    48     *  the file handles for all Cortex-A and Cortex-M GNU targets.
    49     *
    50     *  Adding Semi-Hosting support to a SYS/BIOS application requires linking
    51     *  with a semi-hosting gnu library called "librdimon" and including this
    52     *  module in the config script.
    53     *
    54     *  Here's an example of including this module in the *.cfg file.
    55     *  @p(code)
    56     *      var SemiHost = xdc.useModule('ti.sysbios.rts.gnu.SemiHostSupport');
    57     *  @p
    58     *
    59     *  The following examples illustrate how to link with the Semi-Hosting library
    60     *  in the different build flows supported by SYS/BIOS:
    61     *
    62     *  - When using package.bld build flow, the following code needs to be added to
    63     *    the config.bld file:
    64     *
    65     *  @p(code)
    66     *      var gccArmTargets = xdc.loadPackage('gnu.targets.arm');
    67     *
    68     *      // For Cortex-A8 target
    69     *      gccArmTargets.A8F.bspLib = "rdimon";
    70     *
    71     *      // For Cortex-A9 target
    72     *      gccArmTargets.A9F.bspLib = "rdimon";
    73     *
    74     *      // For Cortex-A15 target
    75     *      gccArmTargets.A15F.bspLib = "rdimon";
    76     *
    77     *      // For Cortex-M3 target
    78     *      gccArmTargets.M3.bspLib = "rdimon";
    79     *
    80     *      // For Cortex-M4 target
    81     *      gccArmTargets.M4.bspLib = "rdimon";
    82     *
    83     *      // For Cortex-M4F target
    84     *      gccArmTargets.M4F.bspLib = "rdimon";
    85     *  @p
    86     *
    87     *  - When using configuro or building a CCS project, the user needs to add
    88     *    the following link options to link with the librdimon.a library.
    89     *
    90     *  @p(code)
    91     *      -Wl,--start-group -lrdimon -Wl,--end-group
    92     *  @p
    93     *
    94     *  @a(Note)
    95     *  If the SemiHostSupport module is used without linking with the librdimon
    96     *  library, the application build will generate a linker error. The linker
    97     *  complaints about a missing "initialise_monitor_handles" symbol which is
    98     *  defined in librdimon library. Please do not include this module if you
    99     *  are not linking with librdimon library to avoid any linker errors.
   100     */
   101    
   102    @Template ("./SemiHostSupport.xdt") /* generate SVC_Handler() function */
   103    
   104    module SemiHostSupport
   105    {
   106    
   107    internal:
   108    
   109        /*!
   110         *  ======== startup ========
   111         *  startup function to initialize semi-hosting file handles early
   112         *  during climb-up
   113         */
   114        Void startup();
   115    
   116    }