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