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 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52
53
54 package ti.sdo.ipc;
55
56 import xdc.runtime.Assert;
57 import xdc.runtime.Diags;
58
59 import xdc.rov.ViewInfo;
60
61 import ti.sdo.utils.List;
62
63 import ti.sdo.ipc.interfaces.INotifyDriver;
64
65 /*!
66 * ======== Notify ========
67 * Notification manager
68 *
69 * @p(html)
70 * This module has a common header that can be found in the {@link ti.ipc}
71 * package. Application code should include the common header file (not the
72 * RTSC-generated one):
73 *
74 * <PRE>#include <ti/ipc/Notify.h></PRE>
75 *
76 * The RTSC module must be used in the application's RTSC configuration file
77 * (.cfg) if runtime APIs will be used in the application:
78 *
79 * <PRE>Notify = xdc.useModule('ti.sdo.ipc.Notify');</PRE>
80 *
81 * Documentation for all runtime APIs, instance configuration parameters,
82 * error codes macros and type definitions available to the application
83 * integrator can be found in the
84 * <A HREF="../../../../doxygen/html/files.html">Doxygen documenation</A>
85 * for the IPC product. However, the documentation presented on this page
86 * should be referred to for information specific to the RTSC module, such as
87 * module configuration, Errors, and Asserts.
88 * @p
89 *
90 * The Notify module typically doesn't require much (if any) configuration at
91 * static time. However, it is possible to reduce the amount of shared memory
92 * used by the Notify subsystem by reducing the value of {@link #numEvents}.
93 */
94
95 @Gated
96 @ModuleStartup
97 @InstanceInitError
98 @InstanceFinalize
99
100 module Notify
101 {
102 /*! @_nodoc */
103 metaonly struct BasicView {
104 UInt remoteProcId;
105 String remoteProcName;
106 UInt lineId;
107 UInt disabled;
108 }
109
110 /*! @_nodoc */
111 metaonly struct EventDataView {
112 UInt eventId;
113 String fnNotifyCbck;
114 String cbckArg;
115 }
116
117 /*!
118 * ======== rovViewInfo ========
119 */
120 @Facet
121 metaonly config ViewInfo.Instance rovViewInfo =
122 ViewInfo.create({
123 viewMap: [
124 ['Basic',
125 {
126 type: ViewInfo.INSTANCE,
127 viewInitFxn: 'viewInitBasic',
128 structName: 'BasicView'
129 }
130 ],
131 ['EventListeners',
132 {
133 type: ViewInfo.INSTANCE_DATA,
134 viewInitFxn: 'viewInitData',
135 structName: 'EventDataView'
136 }
137 ],
138 ]
139 });
140
141 /*!
142 * Assert raised when trying to re-register for given line and processor
143 */
144 config Assert.Id A_alreadyRegistered =
145 {msg: "A_alreadyRegistered: Notify instance for the processor/line already registered"};
146
147 /*!
148 * Assert raised when trying to use an unregistered Notify instance
149 */
150 config Assert.Id A_notRegistered =
151 {msg: "A_notRegistered: Notify instance not yet registered for the processor/line"};
152
153 /*!
154 * Assert raised when trying to improperly use a reserved event
155 */
156 config Assert.Id A_reservedEvent =
157 {msg: "A_reservedEvent: Improper use of a reserved event"};
158
159 /*!
160 * Assert raised when {@link #restore} called with improper key
161 */
162 config Assert.Id A_outOfOrderNesting =
163 {msg: "A_outOfOrderNesting: Out of order nesting"};
164
165 /*!
166 * ======== A_invArgument ========
167 * Assert raised when an argument is invalid
168 */
169 config Assert.Id A_invArgument = {
170 msg: "A_invArgument: Invalid argument supplied"
171 };
172
173 /*!
174 * ======== A_internal ========
175 * Assert raised when an internal error is encountered
176 */
177 config Assert.Id A_internal = {
178 msg: "A_internal: An internal error has occurred"
179 };
180
181 /*!
182 * ======== SetupProxy ========
183 * Device-specific Notify setup proxy
184 */
185 proxy SetupProxy inherits ti.sdo.ipc.interfaces.INotifySetup;
186
187 /*! Maximum number of events supported by the Notify module */
188 const UInt MAXEVENTS = 32;
189
190 /*!
191 * Number of events supported by Notify
192 *
193 * Lowering this value offers the benefit of lower footprint especially in
194 * shared memory.
195 */
196 config UInt numEvents = 32;
197
198 /*!
199 * ======== sendEventPollCount ========
200 * Poll for specified amount before sendEvent times out
201 *
202 * Setting a finite value for sendEventPollCount will cause
203 * Notify_sendEvent to poll for an amount of time
204 * proportional to this value when the 'waitClear' flag is TRUE.
205 */
206 config UInt32 sendEventPollCount = -1;
207
208 /*! @_nodoc
209 * Maximum number of interrupt lines between a single pair of processors
210 *
211 * This config is usually set internally by the NotfiySetup proxy when the
212 * proxy is set up to use more than one line.
213 */
214 config UInt16 numLines = 1;
215
216 /*!
217 * Number of reserved event numbers
218 *
219 * The first reservedEvents event numbers are reserved for
220 * middleware modules. Attempts to use these reserved events
221 * will result in a {@link #A_reservedEvent} assert.
222 *
223 * To use the reserved events, the top 16-bits of the eventId must equal
224 * Notify_SYSTEMKEY.
225 */
226 config UInt16 reservedEvents = 5;
227
228 /*!
229 * @_nodoc
230 * Detach Notify from a remote processor. Should only be called by the Ipc
231 * module during its detach operation.
232 */
233 Int detach(UInt16 remoteProcId);
234
235 instance:
236
237 /*! @_nodoc
238 * Register a created Notify driver with the Notify module
239 *
240 * The Notify module stores a copy of the driverHandle in an array
241 * indexed by procId and lineId. Furture references to the procId
242 * and lineId in Notify APIs will utilize the driver registered using
243 * {@link #create}.
244 *
245 * @param(driverHandle) Notify driver handle
246 * @param(procId) Remote processor id
247 * @param(lineId) Line id
248 */
249 create(INotifyDriver.Handle driverHandle, UInt16 remoteProcId,
250 UInt16 lineId);
251
252 /*! @_nodoc
253 * Called internally by the Notify module or notify driver module
254 * to execute the callback registered to a specific event.
255 */
256 Void exec(UInt32 eventId, UInt32 payload);
257
258 internal:
259
260 /*!
261 * Used to execute a list of callback functions when the callbacks are
262 * registered using registerMany.
263 */
264 Void execMany(UInt16 remoteProcId, UInt16 lineId, UInt32 eventId, UArg arg,
265 UInt32 payload);
266
267 struct EventCallback {
268 Fxn fnNotifyCbck;
269 UArg cbckArg;
270 }
271
272 struct EventListener {
273 List.Elem element;
274 EventCallback callback;
275 }
276
277 struct Instance_State {
278 UInt nesting;
279 INotifyDriver.Handle driverHandle;
280 UInt16 remoteProcId;
281 UInt16 lineId;
282 EventCallback callbacks[];
283 List.Object eventList[];
284 };
285
286 struct Module_State {
287 Handle notifyHandles[][];
288
289 290 291
292 Bits32 localEnableMask;
293 }
294
295 }