[processor-sdk/performance-audio-sr.git] / processor_audio_sdk_1_00_00_00 / psdk_cust / ipc_3_43_00_00_eng / docs / cdoc / ti / sdo / ipc / ListMP-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.ListMP</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"> * ======== ListMP.xdc ========
41 </span> 34 <span class="comment"> *
42 </span> 35 <span class="comment"> */</span>
43 36
44 37 import xdc.runtime.Error;
45 38 import ti.sdo.utils.NameServer;
46 39
47 40 <span class="xdoc">/*!
48 </span> 41 <span class="xdoc"> * ======== ListMP ========
49 </span> 42 <span class="xdoc"> * Shared memory linked list
50 </span> 43 <span class="xdoc"> *
51 </span> 44 <span class="xdoc"> * <b>@p(html)</b>
52 </span> 45 <span class="xdoc"> * This module has a common header that can be found in the {<b>@link</b> ti.ipc}
53 </span> 46 <span class="xdoc"> * package. Application code should include the common header file (not the
54 </span> 47 <span class="xdoc"> * RTSC-generated one):
55 </span> 48 <span class="xdoc"> *
56 </span> 49 <span class="xdoc"> * <PRE>#include &lt;ti/ipc/ListMP.h&gt;</PRE>
57 </span> 50 <span class="xdoc"> *
58 </span> 51 <span class="xdoc"> * The RTSC module must be used in the application's RTSC configuration file
59 </span> 52 <span class="xdoc"> * (.cfg):
60 </span> 53 <span class="xdoc"> *
61 </span> 54 <span class="xdoc"> * <PRE>ListMP = xdc.useModule('ti.sdo.ipc.ListMP');</PRE>
62 </span> 55 <span class="xdoc"> *
63 </span> 56 <span class="xdoc"> * Documentation for all runtime APIs, instance configuration parameters,
64 </span> 57 <span class="xdoc"> * error codes macros and type definitions available to the application
65 </span> 58 <span class="xdoc"> * integrator can be found in the
66 </span> 59 <span class="xdoc"> * <A HREF="../../../../doxygen/html/files.html">Doxygen documenation</A>
67 </span> 60 <span class="xdoc"> * for the IPC product. However, the documentation presented on this page
68 </span> 61 <span class="xdoc"> * should be referred to for information specific to the RTSC module, such as
69 </span> 62 <span class="xdoc"> * module configuration, Errors, and Asserts.
70 </span> 63 <span class="xdoc"> * <b>@p</b>
71 </span> 64 <span class="xdoc"> */</span>
72 65 @InstanceInitError <span class="comment">/* Initialization may throw errors */</span>
73 66 @InstanceFinalize
74 67
75 68 <span class=key>module</span> ListMP
76 69 {
77 70 <span class="xdoc">/*!
78 </span> 71 <span class="xdoc"> * ======== BasicView ========
79 </span> 72 <span class="xdoc"> * <b>@_nodoc</b>
80 </span> 73 <span class="xdoc"> * ROV view structure representing a ListMP instance.
81 </span> 74 <span class="xdoc"> */</span>
82 75 <span class=key>metaonly</span> <span class=key>struct</span> BasicView {
83 76 String label;
84 77 String type;
85 78 String gate;
86 79 }
87 80
88 81 <span class="xdoc">/*!
89 </span> 82 <span class="xdoc"> * ======== ElemView ========
90 </span> 83 <span class="xdoc"> * <b>@_nodoc</b>
91 </span> 84 <span class="xdoc"> * ROV view structure representing a single list element.
92 </span> 85 <span class="xdoc"> */</span>
93 86 <span class=key>metaonly</span> <span class=key>struct</span> ElemView {
94 87 Int index;
95 88 String srPtr;
96 89 String addr;
97 90 }
98 91
99 92 <span class="xdoc">/*!
100 </span> 93 <span class="xdoc"> * ======== rovViewInfo ========
101 </span> 94 <span class="xdoc"> * <b>@_nodoc</b>
102 </span> 95 <span class="xdoc"> */</span>
103 96 @Facet
104 97 <span class=key>metaonly</span> <span class=key>config</span> xdc.rov.ViewInfo.Instance rovViewInfo =
105 98 xdc.rov.ViewInfo.create({
106 99 viewMap: [
107 100 [<span class="string">'Basic'</span>,
108 101 {
109 102 type: xdc.rov.ViewInfo.INSTANCE,
110 103 viewInitFxn: <span class="string">'viewInitBasic'</span>,
111 104 structName: <span class="string">'BasicView'</span>
112 105 }
113 106 ],
114 107 [<span class="string">'Lists'</span>,
115 108 {
116 109 type: xdc.rov.ViewInfo.INSTANCE_DATA,
117 110 viewInitFxn: <span class="string">'viewInitLists'</span>,
118 111 structName: <span class="string">'ElemView'</span>
119 112 }
120 113 ],
121 114 ]
122 115 });
123 116
124 117 <span class="xdoc">/*!
125 </span> 118 <span class="xdoc"> * ======== maxRuntimeEntries ========
126 </span> 119 <span class="xdoc"> * Maximum number of ListMP's that can be dynamically created
127 </span> 120 <span class="xdoc"> * and added to the NameServer.
128 </span> 121 <span class="xdoc"> */</span>
129 122 <span class=key>metaonly</span> <span class=key>config</span> UInt maxRuntimeEntries = NameServer.ALLOWGROWTH;
130 123
131 124 <span class="xdoc">/*!
132 </span> 125 <span class="xdoc"> * ======== maxNameLen ========
133 </span> 126 <span class="xdoc"> * Maximum length for names.
134 </span> 127 <span class="xdoc"> */</span>
135 128 <span class=key>metaonly</span> <span class=key>config</span> UInt maxNameLen = 32;
136 129
137 130 <span class="xdoc">/*!
138 </span> 131 <span class="xdoc"> * ======== tableSection ========
139 </span> 132 <span class="xdoc"> * Section name is used to place the names table
140 </span> 133 <span class="xdoc"> */</span>
141 134 <span class=key>metaonly</span> <span class=key>config</span> String tableSection = <span class=key>null</span>;
142 135
143 136
144 137 <span class=key>instance</span>:
145 138
146 139 <span class="xdoc">/*!
147 </span> 140 <span class="xdoc"> * ======== gate ========
148 </span> 141 <span class="xdoc"> * GateMP used for critical region management of the shared memory
149 </span> 142 <span class="xdoc"> *
150 </span> 143 <span class="xdoc"> * Using the default value of NULL will result in the default GateMP
151 </span> 144 <span class="xdoc"> * being used for context protection.
152 </span> 145 <span class="xdoc"> */</span>
153 146 <span class=key>config</span> GateMP.Handle gate = <span class=key>null</span>;
154 147
155 148 <span class="xdoc">/*! <b>@_nodoc</b>
156 </span> 149 <span class="xdoc"> * ======== openFlag ========
157 </span> 150 <span class="xdoc"> * Set to 'true' by the {<b>@link</b> #open}.
158 </span> 151 <span class="xdoc"> */</span>
159 152 <span class=key>config</span> Bool openFlag = <span class=key>false</span>;
160 153
161 154 <span class="xdoc">/*! <b>@_nodoc</b>
162 </span> 155 <span class="xdoc"> * ======== sharedAddr ========
163 </span> 156 <span class="xdoc"> * Physical address of the shared memory
164 </span> 157 <span class="xdoc"> *
165 </span> 158 <span class="xdoc"> * The shared memory that will be used for maintaining shared state
166 </span> 159 <span class="xdoc"> * information. This is an optional parameter to create. If value
167 </span> 160 <span class="xdoc"> * is null, then the shared memory for the new instance will be
168 </span> 161 <span class="xdoc"> * allocated from the heap in {<b>@link</b> #regionId}.
169 </span> 162 <span class="xdoc"> */</span>
170 163 <span class=key>config</span> Ptr sharedAddr = <span class=key>null</span>;
171 164
172 165 <span class="xdoc">/*!
173 </span> 166 <span class="xdoc"> * ======== name ========
174 </span> 167 <span class="xdoc"> * Name of the instance
175 </span> 168 <span class="xdoc"> *
176 </span> 169 <span class="xdoc"> * The name must be unique among all ListMP instances in the sytem.
177 </span> 170 <span class="xdoc"> * When using {<b>@link</b> #regionId} to create a new instance, the name must
178 </span> 171 <span class="xdoc"> * not be null.
179 </span> 172 <span class="xdoc"> */</span>
180 173 <span class=key>config</span> String name = <span class=key>null</span>;
181 174
182 175 <span class="xdoc">/*!
183 </span> 176 <span class="xdoc"> * ======== regionId ========
184 </span> 177 <span class="xdoc"> * SharedRegion ID.
185 </span> 178 <span class="xdoc"> *
186 </span> 179 <span class="xdoc"> * The ID corresponding to the index of the shared region in which this
187 </span> 180 <span class="xdoc"> * shared instance is to be placed. This is used in create() only when
188 </span> 181 <span class="xdoc"> * {<b>@link</b> #name} is not null.
189 </span> 182 <span class="xdoc"> */</span>
190 183 <span class=key>config</span> UInt16 regionId = 0;
191 184
192 185 <span class="xdoc">/*! <b>@_nodoc</b>
193 </span> 186 <span class="xdoc"> * ======== metaListMP ========
194 </span> 187 <span class="xdoc"> * Used to store elem before the object is initialized.
195 </span> 188 <span class="xdoc"> */</span>
196 189 <span class=key>metaonly</span> <span class=key>config</span> any metaListMP[];
197 190
198 191
199 192 <span class=key>internal</span>: <span class="comment">/* not for client use */</span>
200 193
201 194 <span class=key>const</span> UInt32 CREATED = 0x12181964;
202 195
203 196 <span class="xdoc">/*!
204 </span> 197 <span class="xdoc"> * ======== Elem ========
205 </span> 198 <span class="xdoc"> * Opaque ListMP element
206 </span> 199 <span class="xdoc"> *
207 </span> 200 <span class="xdoc"> * A field of this type must be placed at the head of client structs.
208 </span> 201 <span class="xdoc"> */</span>
209 202 @Opaque <span class=key>struct</span> Elem {
210 203 volatile SharedRegion.SRPtr next; <span class="comment">/* volatile for whole_program */</span>
211 204 volatile SharedRegion.SRPtr prev; <span class="comment">/* volatile for whole_program */</span>
212 205 };
213 206
214 207
215 208 <span class="xdoc">/*!
216 </span> 209 <span class="xdoc"> * ======== nameSrvPrms ========
217 </span> 210 <span class="xdoc"> * This Params object is used for temporary storage of the
218 </span> 211 <span class="xdoc"> * module wide parameters that are for setting the NameServer instance.
219 </span> 212 <span class="xdoc"> */</span>
220 213 <span class=key>metaonly</span> <span class=key>config</span> NameServer.Params nameSrvPrms;
221 214
222 215 <span class="xdoc">/*!
223 </span> 216 <span class="xdoc"> * ======== elemClear ========
224 </span> 217 <span class="xdoc"> * Clears a ListMP element's pointers
225 </span> 218 <span class="xdoc"> *
226 </span> 219 <span class="xdoc"> * This API is not for removing elements from a ListMP, and
227 </span> 220 <span class="xdoc"> * should never be called on an element in a ListMP--only on deListed
228 </span> 221 <span class="xdoc"> * elements.
229 </span> 222 <span class="xdoc"> *
230 </span> 223 <span class="xdoc"> * <b>@param(elem)</b> element to be cleared
231 </span> 224 <span class="xdoc"> */</span>
232 225 Void elemClear(Elem *elem);
233 226
234 227 <span class="comment">/* Initialize shared memory */</span>
235 228 Void postInit(Object *obj, Error.Block *eb);
236 229
237 230 <span class="xdoc">/*! Structure of attributes in shared memory */</span>
238 231 <span class=key>struct</span> Attrs {
239 232 Bits32 status; <span class="comment">/* Created stamp */</span>
240 233 SharedRegion.SRPtr gateMPAddr; <span class="comment">/* GateMP SRPtr (shm safe) */</span>
241 234 Elem head; <span class="comment">/* head of list */</span>
242 235 };
243 236
244 237 <span class="comment">/* instance object */</span>
245 238 <span class=key>struct</span> Instance_State {
246 239 Attrs *attrs; <span class="comment">/* local pointer to attrs */</span>
247 240 Ptr nsKey; <span class="comment">/* for removing NS entry */</span>
248 241 Ipc.ObjType objType; <span class="comment">/* Static/Dynamic? open/creator? */</span>
249 242 GateMP.Handle gate; <span class="comment">/* Gate for critical regions */</span>
250 243 SizeT allocSize; <span class="comment">/* Shared memory allocated */</span>
251 244 UInt16 regionId; <span class="comment">/* SharedRegion ID */</span>
252 245 Bool cacheEnabled; <span class="comment">/* Whether to do cache calls */</span>
253 246 SizeT cacheLineSize; <span class="comment">/* The region cache line size */</span>
254 247 };
255 248
256 249 <span class="comment">/* module object */</span>
257 250 <span class=key>struct</span> Module_State {
258 251 NameServer.Handle nameServer;
259 252 };
260 253 }
261 </pre>
262 </body></html>