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