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