[processor-sdk/performance-audio-sr.git] / ipc_3_43_00_00_eng / docs / cdoc / ti / sdo / ipc / Notify-src.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <html><head><title>module ti.sdo.ipc.Notify</title>
3 <meta name="googlebot" content="noindex,nofollow">
4 <link rel="stylesheet" type="text/css" href="../../../src.css"/>
5 </head>
6 <body>
7 <pre class=src>
8 1 <span class="comment">/*
9 </span> 2 <span class="comment"> * Copyright (c) 2012-2013, Texas Instruments Incorporated
10 </span> 3 <span class="comment"> * All rights reserved.
11 </span> 4 <span class="comment"> *
12 </span> 5 <span class="comment"> * Redistribution and use in source and binary forms, with or without
13 </span> 6 <span class="comment"> * modification, are permitted provided that the following conditions
14 </span> 7 <span class="comment"> * are met:
15 </span> 8 <span class="comment"> *
16 </span> 9 <span class="comment"> * * Redistributions of source code must retain the above copyright
17 </span> 10 <span class="comment"> * notice, this list of conditions and the following disclaimer.
18 </span> 11 <span class="comment"> *
19 </span> 12 <span class="comment"> * * Redistributions in binary form must reproduce the above copyright
20 </span> 13 <span class="comment"> * notice, this list of conditions and the following disclaimer in the
21 </span> 14 <span class="comment"> * documentation and/or other materials provided with the distribution.
22 </span> 15 <span class="comment"> *
23 </span> 16 <span class="comment"> * * Neither the name of Texas Instruments Incorporated nor the names of
24 </span> 17 <span class="comment"> * its contributors may be used to endorse or promote products derived
25 </span> 18 <span class="comment"> * from this software without specific prior written permission.
26 </span> 19 <span class="comment"> *
27 </span> 20 <span class="comment"> * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
28 </span> 21 <span class="comment"> * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
29 </span> 22 <span class="comment"> * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
30 </span> 23 <span class="comment"> * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
31 </span> 24 <span class="comment"> * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
32 </span> 25 <span class="comment"> * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
33 </span> 26 <span class="comment"> * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
34 </span> 27 <span class="comment"> * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
35 </span> 28 <span class="comment"> * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
36 </span> 29 <span class="comment"> * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
37 </span> 30 <span class="comment"> * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
38 </span> 31 <span class="comment"> */</span>
39 32 <span class="comment">/*
40 </span> 33 <span class="comment"> * ======== Notify.xdc ========
41 </span> 34 <span class="comment"> *
42 </span> 35 <span class="comment"> */</span>
43 36
44 37 <span class=key>package</span> ti.sdo.ipc;
45 38
46 39 import xdc.runtime.Assert;
47 40 import xdc.runtime.Diags;
48 41
49 42 import xdc.rov.ViewInfo;
50 43
51 44 import ti.sdo.utils.List;
52 45
53 46 import ti.sdo.ipc.interfaces.INotifyDriver;
54 47
55 48 <span class="xdoc">/*!
56 </span> 49 <span class="xdoc"> * ======== Notify ========
57 </span> 50 <span class="xdoc"> * Notification manager
58 </span> 51 <span class="xdoc"> *
59 </span> 52 <span class="xdoc"> * <b>@p(html)</b>
60 </span> 53 <span class="xdoc"> * This module has a common header that can be found in the {<b>@link</b> ti.ipc}
61 </span> 54 <span class="xdoc"> * package. Application code should include the common header file (not the
62 </span> 55 <span class="xdoc"> * RTSC-generated one):
63 </span> 56 <span class="xdoc"> *
64 </span> 57 <span class="xdoc"> * <PRE>#include &lt;ti/ipc/Notify.h&gt;</PRE>
65 </span> 58 <span class="xdoc"> *
66 </span> 59 <span class="xdoc"> * The RTSC module must be used in the application's RTSC configuration file
67 </span> 60 <span class="xdoc"> * (.cfg) if runtime APIs will be used in the application:
68 </span> 61 <span class="xdoc"> *
69 </span> 62 <span class="xdoc"> * <PRE>Notify = xdc.useModule('ti.sdo.ipc.Notify');</PRE>
70 </span> 63 <span class="xdoc"> *
71 </span> 64 <span class="xdoc"> * Documentation for all runtime APIs, instance configuration parameters,
72 </span> 65 <span class="xdoc"> * error codes macros and type definitions available to the application
73 </span> 66 <span class="xdoc"> * integrator can be found in the
74 </span> 67 <span class="xdoc"> * <A HREF="../../../../doxygen/html/files.html">Doxygen documenation</A>
75 </span> 68 <span class="xdoc"> * for the IPC product. However, the documentation presented on this page
76 </span> 69 <span class="xdoc"> * should be referred to for information specific to the RTSC module, such as
77 </span> 70 <span class="xdoc"> * module configuration, Errors, and Asserts.
78 </span> 71 <span class="xdoc"> * <b>@p</b>
79 </span> 72 <span class="xdoc"> *
80 </span> 73 <span class="xdoc"> * The Notify module typically doesn't require much (if any) configuration at
81 </span> 74 <span class="xdoc"> * static time. However, it is possible to reduce the amount of shared memory
82 </span> 75 <span class="xdoc"> * used by the Notify subsystem by reducing the value of {<b>@link</b> #numEvents}.
83 </span> 76 <span class="xdoc"> */</span>
84 77
85 78 @Gated
86 79 @ModuleStartup
87 80 @InstanceInitError
88 81 @InstanceFinalize
89 82
90 83 <span class=key>module</span> Notify
91 84 {
92 85 <span class="xdoc">/*! <b>@_nodoc</b> */</span>
93 86 <span class=key>metaonly</span> <span class=key>struct</span> BasicView {
94 87 UInt remoteProcId;
95 88 String remoteProcName;
96 89 UInt lineId;
97 90 UInt disabled;
98 91 }
99 92
100 93 <span class="xdoc">/*! <b>@_nodoc</b> */</span>
101 94 <span class=key>metaonly</span> <span class=key>struct</span> EventDataView {
102 95 UInt eventId;
103 96 String fnNotifyCbck;
104 97 String cbckArg;
105 98 }
106 99
107 100 <span class="xdoc">/*!
108 </span> 101 <span class="xdoc"> * ======== rovViewInfo ========
109 </span> 102 <span class="xdoc"> */</span>
110 103 @Facet
111 104 <span class=key>metaonly</span> <span class=key>config</span> ViewInfo.Instance rovViewInfo =
112 105 ViewInfo.create({
113 106 viewMap: [
114 107 [<span class="string">'Basic'</span>,
115 108 {
116 109 type: ViewInfo.INSTANCE,
117 110 viewInitFxn: <span class="string">'viewInitBasic'</span>,
118 111 structName: <span class="string">'BasicView'</span>
119 112 }
120 113 ],
121 114 [<span class="string">'EventListeners'</span>,
122 115 {
123 116 type: ViewInfo.INSTANCE_DATA,
124 117 viewInitFxn: <span class="string">'viewInitData'</span>,
125 118 structName: <span class="string">'EventDataView'</span>
126 119 }
127 120 ],
128 121 ]
129 122 });
130 123
131 124 <span class="xdoc">/*!
132 </span> 125 <span class="xdoc"> * Assert raised when trying to re-register for given line and processor
133 </span> 126 <span class="xdoc"> */</span>
134 127 <span class=key>config</span> Assert.Id A_alreadyRegistered =
135 128 {msg: <span class="string">"A_alreadyRegistered: Notify instance for the processor/line already registered"</span>};
136 129
137 130 <span class="xdoc">/*!
138 </span> 131 <span class="xdoc"> * Assert raised when trying to use an unregistered Notify instance
139 </span> 132 <span class="xdoc"> */</span>
140 133 <span class=key>config</span> Assert.Id A_notRegistered =
141 134 {msg: <span class="string">"A_notRegistered: Notify instance not yet registered for the processor/line"</span>};
142 135
143 136 <span class="xdoc">/*!
144 </span> 137 <span class="xdoc"> * Assert raised when trying to improperly use a reserved event
145 </span> 138 <span class="xdoc"> */</span>
146 139 <span class=key>config</span> Assert.Id A_reservedEvent =
147 140 {msg: <span class="string">"A_reservedEvent: Improper use of a reserved event"</span>};
148 141
149 142 <span class="xdoc">/*!
150 </span> 143 <span class="xdoc"> * Assert raised when {<b>@link</b> #restore} called with improper key
151 </span> 144 <span class="xdoc"> */</span>
152 145 <span class=key>config</span> Assert.Id A_outOfOrderNesting =
153 146 {msg: <span class="string">"A_outOfOrderNesting: Out of order nesting"</span>};
154 147
155 148 <span class="xdoc">/*!
156 </span> 149 <span class="xdoc"> * ======== A_invArgument ========
157 </span> 150 <span class="xdoc"> * Assert raised when an argument is invalid
158 </span> 151 <span class="xdoc"> */</span>
159 152 <span class=key>config</span> Assert.Id A_invArgument = {
160 153 msg: <span class="string">"A_invArgument: Invalid argument supplied"</span>
161 154 };
162 155
163 156 <span class="xdoc">/*!
164 </span> 157 <span class="xdoc"> * ======== A_internal ========
165 </span> 158 <span class="xdoc"> * Assert raised when an internal error is encountered
166 </span> 159 <span class="xdoc"> */</span>
167 160 <span class=key>config</span> Assert.Id A_internal = {
168 161 msg: <span class="string">"A_internal: An internal error has occurred"</span>
169 162 };
170 163
171 164 <span class="xdoc">/*!
172 </span> 165 <span class="xdoc"> * ======== SetupProxy ========
173 </span> 166 <span class="xdoc"> * Device-specific Notify setup proxy
174 </span> 167 <span class="xdoc"> */</span>
175 168 <span class=key>proxy</span> SetupProxy <span class=key>inherits</span> ti.sdo.ipc.interfaces.INotifySetup;
176 169
177 170 <span class="xdoc">/*! Maximum number of events supported by the Notify module */</span>
178 171 <span class=key>const</span> UInt MAXEVENTS = 32;
179 172
180 173 <span class="xdoc">/*!
181 </span> 174 <span class="xdoc"> * Number of events supported by Notify
182 </span> 175 <span class="xdoc"> *
183 </span> 176 <span class="xdoc"> * Lowering this value offers the benefit of lower footprint especially in
184 </span> 177 <span class="xdoc"> * shared memory.
185 </span> 178 <span class="xdoc"> */</span>
186 179 <span class=key>config</span> UInt numEvents = 32;
187 180
188 181 <span class="xdoc">/*!
189 </span> 182 <span class="xdoc"> * ======== sendEventPollCount ========
190 </span> 183 <span class="xdoc"> * Poll for specified amount before sendEvent times out
191 </span> 184 <span class="xdoc"> *
192 </span> 185 <span class="xdoc"> * Setting a finite value for sendEventPollCount will cause
193 </span> 186 <span class="xdoc"> * Notify_sendEvent to poll for an amount of time
194 </span> 187 <span class="xdoc"> * proportional to this value when the 'waitClear' flag is TRUE.
195 </span> 188 <span class="xdoc"> */</span>
196 189 <span class=key>config</span> UInt32 sendEventPollCount = -1;
197 190
198 191 <span class="xdoc">/*! <b>@_nodoc</b>
199 </span> 192 <span class="xdoc"> * Maximum number of interrupt lines between a single pair of processors
200 </span> 193 <span class="xdoc"> *
201 </span> 194 <span class="xdoc"> * This config is usually set internally by the NotfiySetup proxy when the
202 </span> 195 <span class="xdoc"> * proxy is set up to use more than one line.
203 </span> 196 <span class="xdoc"> */</span>
204 197 <span class=key>config</span> UInt16 numLines = 1;
205 198
206 199 <span class="xdoc">/*!
207 </span> 200 <span class="xdoc"> * Number of reserved event numbers
208 </span> 201 <span class="xdoc"> *
209 </span> 202 <span class="xdoc"> * The first reservedEvents event numbers are reserved for
210 </span> 203 <span class="xdoc"> * middleware modules. Attempts to use these reserved events
211 </span> 204 <span class="xdoc"> * will result in a {<b>@link</b> #A_reservedEvent} assert.
212 </span> 205 <span class="xdoc"> *
213 </span> 206 <span class="xdoc"> * To use the reserved events, the top 16-bits of the eventId must equal
214 </span> 207 <span class="xdoc"> * Notify_SYSTEMKEY.
215 </span> 208 <span class="xdoc"> */</span>
216 209 <span class=key>config</span> UInt16 reservedEvents = 5;
217 210
218 211 <span class="xdoc">/*!
219 </span> 212 <span class="xdoc"> * <b>@_nodoc</b>
220 </span> 213 <span class="xdoc"> * Detach Notify from a remote processor. Should only be called by the Ipc
221 </span> 214 <span class="xdoc"> * module during its detach operation.
222 </span> 215 <span class="xdoc"> */</span>
223 216 Int detach(UInt16 remoteProcId);
224 217
225 218 <span class=key>instance</span>:
226 219
227 220 <span class="xdoc">/*! <b>@_nodoc</b>
228 </span> 221 <span class="xdoc"> * Register a created Notify driver with the Notify module
229 </span> 222 <span class="xdoc"> *
230 </span> 223 <span class="xdoc"> * The Notify module stores a copy of the driverHandle in an array
231 </span> 224 <span class="xdoc"> * indexed by procId and lineId. Furture references to the procId
232 </span> 225 <span class="xdoc"> * and lineId in Notify APIs will utilize the driver registered using
233 </span> 226 <span class="xdoc"> * {<b>@link</b> #create}.
234 </span> 227 <span class="xdoc"> *
235 </span> 228 <span class="xdoc"> * <b>@param(driverHandle)</b> Notify driver handle
236 </span> 229 <span class="xdoc"> * <b>@param(procId)</b> Remote processor id
237 </span> 230 <span class="xdoc"> * <b>@param(lineId)</b> Line id
238 </span> 231 <span class="xdoc"> */</span>
239 232 create(INotifyDriver.Handle driverHandle, UInt16 remoteProcId,
240 233 UInt16 lineId);
241 234
242 235 <span class="xdoc">/*! <b>@_nodoc</b>
243 </span> 236 <span class="xdoc"> * Called internally by the Notify module or notify driver module
244 </span> 237 <span class="xdoc"> * to execute the callback registered to a specific event.
245 </span> 238 <span class="xdoc"> */</span>
246 239 Void exec(UInt32 eventId, UInt32 payload);
247 240
248 241 <span class=key>internal</span>:
249 242
250 243 <span class="xdoc">/*!
251 </span> 244 <span class="xdoc"> * Used to execute a list of callback functions when the callbacks are
252 </span> 245 <span class="xdoc"> * registered using registerMany.
253 </span> 246 <span class="xdoc"> */</span>
254 247 Void execMany(UInt16 remoteProcId, UInt16 lineId, UInt32 eventId, UArg arg,
255 248 UInt32 payload);
256 249
257 250 <span class=key>struct</span> EventCallback {
258 251 Fxn fnNotifyCbck;
259 252 UArg cbckArg;
260 253 }
261 254
262 255 <span class=key>struct</span> EventListener {
263 256 List.Elem element; <span class="comment">/* List elem */</span>
264 257 EventCallback callback;
265 258 }
266 259
267 260 <span class=key>struct</span> Instance_State {
268 261 UInt nesting; <span class="comment">/* Disable/restore nesting */</span>
269 262 INotifyDriver.Handle driverHandle; <span class="comment">/* Driver handle */</span>
270 263 UInt16 remoteProcId; <span class="comment">/* Remote MultiProc id */</span>
271 264 UInt16 lineId; <span class="comment">/* Interrupt line id */</span>
272 265 EventCallback callbacks[]; <span class="comment">/* indexed by eventId */</span>
273 266 List.Object eventList[]; <span class="comment">/* indexed by eventId */</span>
274 267 };
275 268
276 269 <span class=key>struct</span> Module_State {
277 270 Handle notifyHandles[][]; <span class="comment">/* indexed by procId then lineId */</span>
278 271
279 272 <span class="comment">/*
280 </span> 273 <span class="comment"> * these fields are used for local/loopback events
281 </span> 274 <span class="comment"> */</span>
282 275 Bits32 localEnableMask; <span class="comment">/* default to enabled (-1) */</span>
283 276 }
284 277
285 278 }
286 </pre>
287 </body></html>