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