1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
32 33 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
108
109 module GateMutex inherits xdc.runtime.IGateProvider
110 {
111
112 /*!
113 * ======== BasicView ========
114 * @_nodoc
115 */
116 metaonly struct BasicView {
117 String status;
118 String owner;
119 String pendedTasks[];
120 }
121
122 /*!
123 * ======== rovViewInfo ========
124 * @_nodoc
125 */
126 @Facet
127 metaonly config 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 override IArg enter();
167
168 override Void leave(IArg key);
169
170 internal:
171
172
173 struct Instance_State {
174 ti.sysbios.knl.Task.Handle owner;
175 ti.sysbios.knl.Semaphore.Object sem;
176 };
177
178 }