1    /* 
     2     * Copyright (c) 2012, 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     *  ======== GateSwi.xdc ========
    34     *
    35     **! 30-Nov-2006 toddm   Code reviewed
    36     */
    37    package ti.sysbios.gates
    38    
    39    import xdc.rov.ViewInfo;
    40    import xdc.runtime.Assert;
    41    
    42    /*!
    43     *  ======== GateSwi ========
    44     *  Software Interrupt Gate.
    45     *
    46     *  GateSwi uses disabling and enabling of software interrupts as the
    47     *  resource locking  mechanism. This gate can be used whenever the resource
    48     *  is being shared by Swis or Tasks. This gate cannot be used by a Hwi.
    49     *
    50     *  The duration between the enter and leave should be as short as possible
    51     *  to minimize Swi latency.
    52     *
    53     *  GateSwi inherits from xdc.runtime.IGateProvider, therefore supports nesting.
    54     *
    55     *  @p(html)
    56     *  <h3> Calling Context </h3>
    57     *  <table border="1" cellpadding="3">
    58     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    59     *    </colgroup>
    60     *
    61     *    <tr><th> Function </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th>
    62     *    <th>  Main  </th><th>  Startup  </th></tr>
    63     *    <!--                                           -->
    64     *    <tr><td> {@link #Params_init} </td><td>   Y    </td><td>   Y    </td>
    65     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    66     *    <tr><td> {@link #query}       </td><td>   Y    </td><td>   Y    </td>
    67     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    68     *    <tr><td> {@link #construct}   </td><td>   Y    </td><td>   Y    </td>
    69     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    70     *    <tr><td> {@link #create}      </td><td>   N*   </td><td>   N*   </td>
    71     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    72     *    <tr><td> {@link #delete}      </td><td>   N*   </td><td>   N*   </td>
    73     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    74     *    <tr><td> {@link #destruct}    </td><td>   Y    </td><td>   Y    </td>
    75     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    76     *    <tr><td> {@link #enter}       </td><td>   N    </td><td>   Y    </td>
    77     *    <td>   Y    </td><td>   Y**  </td><td>   N    </td></tr>
    78     *    <tr><td> {@link #leave}       </td><td>   N    </td><td>   Y    </td>
    79     *    <td>   Y    </td><td>   Y**  </td><td>   N    </td></tr>
    80     *    <tr><td colspan="6"> Definitions: <br />
    81     *       <ul>
    82     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    83     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    84     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    85     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    86     *           <ul>
    87     *             <li> In your module startup after this module is started 
    88     *    (e.g. GateSwi_Module_startupDone() returns TRUE). </li>
    89     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    90     *             <li> During main().</li>
    91     *             <li> During BIOS.startupFxns.</li>
    92     *           </ul>
    93     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    94     *           <ul>
    95     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    96     *             <li> In your module startup before this module is started 
    97     *    (e.g. GateSwi_Module_startupDone() returns FALSE).</li>
    98     *           </ul>
    99     *       <li> <b>*</b>:  Assuming blocking Heap is used for creation. </li>
   100     *       <li> <b>**</b>: Must be used in enter/leave pairs. </li>
   101     *       </ul>
   102     *    </td></tr>
   103     *
   104     *  </table>
   105     *  @p 
   106     */
   107    
   108    module GateSwi inherits xdc.runtime.IGateProvider
   109    {
   110    
   111        /*!
   112         *  ======== BasicView ========
   113         *  @_nodoc
   114         */
   115        metaonly struct BasicView {
   116            String label;
   117        }
   118        
   119        /*!
   120         *  ======== rovViewInfo ========
   121         *  @_nodoc
   122         */
   123        @Facet
   124        metaonly config ViewInfo.Instance rovViewInfo = 
   125            ViewInfo.create({
   126                viewMap: [
   127                [
   128                    'Basic',
   129                    {
   130                        type: ViewInfo.INSTANCE, 
   131                        viewInitFxn: 'viewInitBasic', 
   132                        structName: 'BasicView'
   133                    }
   134                ],
   135                ]
   136            });
   137        
   138        /*!
   139         * Asserted when {@link #enter} or {@link #leave} is called from a 
   140         * hardware interrupt thread.
   141         */
   142        config Assert.Id A_badContext = {
   143                msg: "A_badContext: bad calling context. May not be entered from a hardware interrupt thread."
   144        };
   145    
   146    instance:
   147    
   148        @DirectCall
   149        override IArg enter();
   150    
   151        @DirectCall
   152        override Void leave(IArg key);
   153    
   154    internal:
   155        
   156        /*! 
   157         *  @_nodoc
   158         *  ======== Instance_State ========
   159         *  XDC requires this be defined, even though it's empty.
   160         */
   161        struct Instance_State {
   162        };
   163    }
   164    /*
   165     *  @(#) ti.sysbios.gates; 2, 0, 0, 0,538; 2-24-2012 11:40:38; /db/vtree/library/trees/avala/avala-q28x/src/ xlibrary
   166    
   167     */
   168