1    /*
     2     * Copyright (c) 2013-2020, 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     *  ======== GateMutex.xdc ========
    34     *
    35     */
    36    package ti.sysbios.gates;
    37    
    38    import xdc.rov.ViewInfo;
    39    import xdc.runtime.Assert;
    40    
    41    /*!
    42     *  ======== GateMutex ========
    43     *  Mutex Gate.
    44     *
    45     *  GateMutex uses a Semaphore as the resource locking mechanism. Each
    46     *  GateMutex instance has its own unique Semaphore. This gate can only be
    47     *  used by a Task as a gate can potentially block. This gate cannot be used
    48     *  by a Hwi or Swi.
    49     *
    50     *  Priority inversion is possible if threads of differing priority use a
    51     *  common GateMutex. See the Priority Inversion section of the SYS/BIOS
    52     *  Users Guide for additional information about priority inversion.
    53     *
    54     *  The task that uses a gate can call enter() any number of times without risk
    55     *  of being blocked, although relinquishing ownership of the gate requires a
    56     *  balanced number of calls to leave().
    57     *
    58     *  @p(html)
    59     *  <h3> Calling Context </h3>
    60     *  <table border="1" cellpadding="3">
    61     *    <colgroup span="1"></colgroup> <colgroup span="5" align="center">
    62     *    </colgroup>
    63     *
    64     *    <tr><th> Function </th><th>  Hwi   </th><th>  Swi   </th><th>  Task  </th>
    65     *    <th>  Main  </th><th>  Startup  </th></tr>
    66     *    <!--                                                        -->
    67     *    <tr><td> {@link #Params_init} </td><td>   Y    </td><td>   Y    </td>
    68     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    69     *    <tr><td> {@link #query}       </td><td>   Y    </td><td>   Y    </td>
    70     *    <td>   Y    </td><td>   Y    </td><td>   Y    </td></tr>
    71     *    <tr><td> {@link #construct}   </td><td>   N    </td><td>   N    </td>
    72     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    73     *    <tr><td> {@link #create}      </td><td>   N*   </td><td>   N*   </td>
    74     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    75     *    <tr><td> {@link #delete}      </td><td>   N*   </td><td>   N*   </td>
    76     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    77     *    <tr><td> {@link #destruct}    </td><td>   N    </td><td>   N    </td>
    78     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    79     *    <tr><td> {@link #enter}       </td><td>   N    </td><td>   N    </td>
    80     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    81     *    <tr><td> {@link #leave}       </td><td>   N    </td><td>   N    </td>
    82     *    <td>   Y    </td><td>   Y    </td><td>   N    </td></tr>
    83     *    <tr><td colspan="6"> Definitions: <br />
    84     *       <ul>
    85     *         <li> <b>Hwi</b>: API is callable from a Hwi thread. </li>
    86     *         <li> <b>Swi</b>: API is callable from a Swi thread. </li>
    87     *         <li> <b>Task</b>: API is callable from a Task thread. </li>
    88     *         <li> <b>Main</b>: API is callable during any of these phases: </li>
    89     *           <ul>
    90     *             <li> In your module startup after this module is started
    91     *    (e.g. GateMutex_Module_startupDone() returns TRUE). </li>
    92     *             <li> During xdc.runtime.Startup.lastFxns. </li>
    93     *             <li> During main().</li>
    94     *             <li> During BIOS.startupFxns.</li>
    95     *           </ul>
    96     *         <li> <b>Startup</b>: API is callable during any of these phases:</li>
    97     *           <ul>
    98     *             <li> During xdc.runtime.Startup.firstFxns.</li>
    99     *             <li> In your module startup before this module is started
   100     *    (e.g. GateMutex_Module_startupDone() returns FALSE).</li>
   101     *           </ul>
   102     *       <li> <b>*</b>:  Assuming blocking Heap is used for creation. </li>
   103     *       <li> <b>**</b>: Must be used in enter/leave pairs. </li>
   104     *       </ul>
   105     *    </td></tr>
   106     *
   107     *  </table>
   108     *  @p
   109     */
   110    
   111    @InstanceFinalize       /* destruct semaphore */
   112    
   113    module GateMutex inherits xdc.runtime.IGateProvider
   114    {
   115    
   116        /*!
   117         *  ======== BasicView ========
   118         *  @_nodoc
   119         */
   120        metaonly struct BasicView {
   121            String status;
   122            String owner;
   123            String pendedTasks[];
   124        }
   125    
   126        /*!
   127         *  ======== rovViewInfo ========
   128         *  @_nodoc
   129         */
   130        @Facet
   131        metaonly config ViewInfo.Instance rovViewInfo =
   132            ViewInfo.create({
   133                viewMap: [
   134                    ['Basic', {type: ViewInfo.INSTANCE,
   135                       viewInitFxn: 'viewInitBasic',
   136                       structName: 'BasicView'}]
   137                ]
   138            });
   139    
   140        /*!
   141         *  Assert when GateMutex_enter() is not called from correct context.
   142         *  GateMutex_enter() can only be called from main() or Task context (not
   143         *  Hwi or Swi).
   144         *
   145         *  Common causes and workarounds for hitting this Assert:
   146         *
   147         *  - Calling printf() from a Hwi or Swi thread.
   148         *  @p(blist)
   149         *          - Use xdc.runtime.System_printf (with SysMin) instead.
   150         *  @p
   151         *  - Calling System_printf() from a Hwi or Swi thread when using SysStd.
   152         *  @p(blist)
   153         *          - Use xdc.runtime.SysMin instead of xdc.runtume.SysStd.
   154         *          - Use a different type of Gate for
   155         *            {@link ti.sysbios.BIOS#rtsGateType BIOS.rtsGateType}
   156         *            (ie {@link ti.sysbios.BIOS#GateHwi BIOS.GateHwi}
   157         *            or {@link ti.sysbios.BIOS#GateSwi BIOS.GateSwi})
   158         *  @p
   159         *  - Calling Memory_alloc() from a Hwi or Swi thread.
   160         *  @p(blist)
   161         *          - Use a different Heap manager
   162         *  @p
   163         */
   164        config Assert.Id A_badContext = {
   165            msg: "A_badContext: bad calling context. See GateMutex API doc for details."
   166        };
   167    
   168    instance:
   169    
   170        override IArg enter();
   171    
   172        override Void leave(IArg key);
   173    
   174    internal:
   175    
   176        /* -------- Internal Structures -------- */
   177        struct Instance_State {
   178            ti.sysbios.knl.Task.Handle         owner;
   179            ti.sysbios.knl.Semaphore.Object    sem;
   180        };
   181    
   182    }