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 * ======== SetupProxy ========
150 * Device-specific Notify setup proxy
151 */
152 proxy SetupProxy inherits ti.sdo.ipc.interfaces.INotifySetup;
153
154 /*! Maximum number of events supported by the Notify module */
155 const UInt MAXEVENTS = 32;
156
157 /*!
158 * Number of events supported by Notify
159 *
160 * Lowering this value offers the benefit of lower footprint especially in
161 * shared memory.
162 */
163 config UInt numEvents = 32;
164
165 /*!
166 * ======== sendEventPollCount ========
167 * Poll for specified amount before sendEvent times out
168 *
169 * Setting a finite value for sendEventPollCount will cause
170 * Notify_sendEvent to poll for an amount of time
171 * proportional to this value.
172 */
173 config UInt32 sendEventPollCount = -1;
174
175 /*! @_nodoc
176 * Maximum number of interrupt lines between a single pair of processors
177 *
178 * This config is usually set internally by the NotfiySetup proxy when the
179 * proxy is set up to use more than one line.
180 */
181 config UInt16 numLines = 1;
182
183 /*!
184 * Number of reserved event numbers
185 *
186 * The first reservedEvents event numbers are reserved for
187 * middleware modules. Attempts to use these reserved events
188 * will result in a {@link #A_reservedEvent} assert.
189 *
190 * To use the reserved events, the top 16-bits of the eventId must equal
191 * Notify_SYSTEMKEY.
192 */
193 config UInt16 reservedEvents = 5;
194
195 /*!
196 * @_nodoc
197 * Detach Notify from a remote processor. Should only be called by the Ipc
198 * module during its detach operation.
199 */
200 Int detach(UInt16 remoteProcId);
201
202 instance:
203
204 /*! @_nodoc
205 * Register a created Notify driver with the Notify module
206 *
207 * The Notify module stores a copy of the driverHandle in an array
208 * indexed by procId and lineId. Furture references to the procId
209 * and lineId in Notify APIs will utilize the driver registered using
210 * {@link #create}.
211 *
212 * @param(driverHandle) Notify driver handle
213 * @param(procId) Remote processor id
214 * @param(lineId) Line id
215 */
216 create(INotifyDriver.Handle driverHandle, UInt16 remoteProcId,
217 UInt16 lineId);
218
219 /*! @_nodoc
220 * Called internally by the Notify module or notify driver module
221 * to execute the callback registered to a specific event.
222 */
223 Void exec(UInt32 eventId, UInt32 payload);
224
225 internal:
226
227 /*!
228 * Used to execute a list of callback functions when the callbacks are
229 * registered using registerMany.
230 */
231 Void execMany(UInt16 remoteProcId, UInt16 lineId, UInt32 eventId, UArg arg,
232 UInt32 payload);
233
234 struct EventCallback {
235 Fxn fnNotifyCbck;
236 UArg cbckArg;
237 }
238
239 struct EventListener {
240 List.Elem element;
241 EventCallback callback;
242 }
243
244 struct Instance_State {
245 UInt nesting;
246 INotifyDriver.Handle driverHandle;
247 UInt16 remoteProcId;
248 UInt16 lineId;
249 EventCallback callbacks[];
250 List.Object eventList[];
251 };
252
253 struct Module_State {
254 Handle notifyHandles[][];
255
256 257 258
259 Bits32 localEnableMask;
260 }
261
262 }
263 264 265
266