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