1 /*
2 * Copyright (c) 2012-2013, Texas Instruments Incorporated
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
32 /*
33 * ======== Notify.xdc ========
34 *
35 */
37 package ti.sdo.ipc;
39 import xdc.runtime.Assert;
40 import xdc.runtime.Diags;
42 import xdc.rov.ViewInfo;
44 import ti.sdo.utils.List;
46 import ti.sdo.ipc.interfaces.INotifyDriver;
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 */
78 @Gated
79 @ModuleStartup
80 @InstanceInitError
81 @InstanceFinalize
83 module Notify
84 {
85 /*! @_nodoc */
86 metaonly struct BasicView {
87 UInt remoteProcId;
88 String remoteProcName;
89 UInt lineId;
90 UInt disabled;
91 }
93 /*! @_nodoc */
94 metaonly struct EventDataView {
95 UInt eventId;
96 String fnNotifyCbck;
97 String cbckArg;
98 }
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 });
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"};
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"};
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"};
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"};
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 };
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 };
164 /*!
165 * ======== SetupProxy ========
166 * Device-specific Notify setup proxy
167 */
168 proxy SetupProxy inherits ti.sdo.ipc.interfaces.INotifySetup;
170 /*! Maximum number of events supported by the Notify module */
171 const UInt MAXEVENTS = 32;
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;
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;
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;
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;
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);
218 instance:
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);
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);
241 internal:
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);
250 struct EventCallback {
251 Fxn fnNotifyCbck;
252 UArg cbckArg;
253 }
255 struct EventListener {
256 List.Elem element; /* List elem */
257 EventCallback callback;
258 }
260 struct Instance_State {
261 UInt nesting; /* Disable/restore nesting */
262 INotifyDriver.Handle driverHandle; /* Driver handle */
263 UInt16 remoteProcId; /* Remote MultiProc id */
264 UInt16 lineId; /* Interrupt line id */
265 EventCallback callbacks[]; /* indexed by eventId */
266 List.Object eventList[]; /* indexed by eventId */
267 };
269 struct Module_State {
270 Handle notifyHandles[][]; /* indexed by procId then lineId */
272 /*
273 * these fields are used for local/loopback events
274 */
275 Bits32 localEnableMask; /* default to enabled (-1) */
276 }
278 }