1 2 3 4 5 6 7 8 9
10 11 12 13 14 15 16 17 18 19 20 21
22
23 package ti.sdo.ipc.heaps;
24
25 import ti.sdo.ipc.SharedRegion;
26 import ti.sdo.ipc.Ipc;
27 import ti.sdo.ipc.GateMP;
28 import ti.sdo.utils.NameServer;
29
30 import xdc.rov.ViewInfo;
31
32 import xdc.runtime.Error;
33 import xdc.runtime.Assert;
34 import xdc.runtime.Memory;
35 import xdc.runtime.Startup;
36
37 /*!
38 * ======== HeapMemMP ========
39 * Multi-processor variable size buffer heap implementation.
40 *
41 * This module has a common header that can be found in the {@link ti.ipc}
42 * package. Application code should include the common header file (not the
43 * RTSC-generated one):
44 *
45 * <PRE>#include <ti/ipc/HeapMemMP.h></PRE>
46 *
47 * The RTSC module must be used in the application's RTSC configuration file
48 * (.cfg) if runtime APIs will be used in the application:
49 *
50 * <PRE>HeapMemMP = xdc.useModule('ti.sdo.ipc.heaps.HeapMemMP');</PRE>
51 *
52 * Documentation for all runtime APIs, instance configuration parameters,
53 * error codes macros and type definitions available to the application
54 * integrator can be found in the
55 * <A HREF="../../../../doxygen/html/files.html">Doxygen documenation</A>
56 * for the IPC product. However, the documentation presented on this page
57 * should be referred to for information specific to the RTSC module, such as
58 * module configuration, Errors, and Asserts.
59 * @p
60 */
61 @InstanceInitError
62 @InstanceFinalize
63
64 module HeapMemMP inherits xdc.runtime.IHeap {
65
66 /*! @_nodoc */
67 metaonly struct BasicView {
68 String name;
69 Ptr buf;
70 Memory.Size totalSize;
71 String objType;
72 Ptr gate;
73 }
74
75 /*! @_nodoc */
76 metaonly struct DetailedView {
77 String name;
78 Ptr buf;
79 Memory.Size totalSize;
80 String objType;
81 Ptr gate;
82 Ptr attrs;
83 Bool cacheEnabled;
84 Memory.Size totalFreeSize;
85 Memory.Size largestFreeSize;
86 }
87
88 /*! @_nodoc */
89 metaonly struct FreeBlockView {
90 String address;
91 String label;
92 String size;
93 }
94
95 /*! @_nodoc */
96 @Facet
97 metaonly config ViewInfo.Instance rovViewInfo =
98 ViewInfo.create({
99 viewMap: [
100 [
101 'Basic',
102 {
103 type: ViewInfo.INSTANCE,
104 viewInitFxn: 'viewInitBasic',
105 structName: 'BasicView'
106 }
107 ],
108 [
109 'Detailed',
110 {
111 type: ViewInfo.INSTANCE,
112 viewInitFxn: 'viewInitDetailed',
113 structName: 'DetailedView'
114 }
115 ],
116 [
117 'FreeList',
118 {
119 type: ViewInfo.INSTANCE_DATA,
120 viewInitFxn: 'viewInitData',
121 structName: 'FreeBlockView'
122 }
123 ]
124 ]
125 });
126
127 /*!
128 * ======== ExtendedStats ========
129 * Stats structure for the getExtendedStats API.
130 *
131 * @field(buf) Local address of the shared buffer
132 * This may be different from the original buf
133 * parameter due to alignment requirements.
134 * @field(size) Size of the shared buffer.
135 * This may be different from the original size
136 * parameter due to alignment requirements.
137 */
138 struct ExtendedStats {
139 Ptr buf;
140 SizeT size;
141 }
142
143 /*!
144 * Assert raised when a block of size 0 is requested.
145 */
146 config Assert.Id A_zeroBlock =
147 {msg: "A_zeroBlock: Cannot allocate size 0"};
148
149 /*!
150 * Assert raised when the requested heap size is too small.
151 */
152 config Assert.Id A_heapSize =
153 {msg: "A_heapSize: Requested heap size is too small"};
154
155 /*!
156 * Assert raised when the requested alignment is not a power of 2.
157 */
158 config Assert.Id A_align =
159 {msg: "A_align: Requested align is not a power of 2"};
160
161 /*!
162 * Assert raised when the free detects that an invalid addr or size.
163 *
164 * This could arise when multiple frees are done on the same buffer or
165 * if corruption occurred.
166 *
167 * This also could occur when an alloc is made with size N and the
168 * free for this buffer specifies size M where M > N. Note: not every
169 * case is detectable.
170 *
171 * This assert can also be caused when passing an invalid addr to free
172 * or if the size is causing the end of the buffer to be
173 * out of the expected range.
174 */
175 config Assert.Id A_invalidFree =
176 {msg: "A_invalidFree: Invalid free"};
177
178 /*!
179 * Maximum runtime entries
180 *
181 * Maximum number of HeapMemMP's that can be dynamically created and
182 * added to the NameServer.
183 *
184 * To minimize the amount of runtime allocation, this parameter allows
185 * the pre-allocation of memory for the HeapMemMP's NameServer table.
186 * The default is to allow growth (i.e. memory allocation when
187 * creating a new instance).
188 */
189 metaonly config UInt maxRuntimeEntries = NameServer.ALLOWGROWTH;
190
191 /*!
192 * Maximum length for heap names
193 */
194 config UInt maxNameLen = 32;
195
196 /*!
197 * Section name is used to place the names table
198 *
199 * The default value of NULL implies that no explicit placement is
200 * performed.
201 */
202 metaonly config String tableSection = null;
203
204 instance:
205
206 /*!
207 * GateMP used for critical region management of the shared memory
208 *
209 * Using the default value of NULL will result in use of the GateMP
210 * system gate for context protection.
211 */
212 config GateMP.Handle gate = null;
213
214 /*! @_nodoc
215 * Set to TRUE by the open() call. No one else should touch this!
216 */
217 config Bool openFlag = false;
218
219 /*!
220 * Name of this instance.
221 *
222 * The name (if not NULL) must be unique among all HeapMemMP
223 * instances in the entire system. When creating a new
224 * heap, it is necessary to supply an instance name.
225 */
226 config String name = null;
227
228 /*!
229 * Shared region ID
230 *
231 * The index corresponding to the shared region from which shared memory
232 * will be allocated.
233 */
234 config UInt32 regionId = 0;
235
236 /*! @_nodoc
237 * Physical address of the shared memory
238 *
239 * This value can be left as 'null' unless it is required to place the
240 * heap at a specific location in shared memory. If sharedAddr is null,
241 * then shared memory for a new instance will be allocated from the
242 * heap belonging to the region identified by {@link #regionId}.
243 */
244 config Ptr sharedAddr = null;
245
246 /*!
247 * Size of {@link #sharedBuf}
248 *
249 * This is the size of the buffer to be used in the HeapMemMP instance.
250 * The actual buffer size in the created instance might actually be less
251 * than the value supplied in 'sharedBufSize' because of alignment
252 * constraints.
253 *
254 * It is important to note that the total amount of shared memory required
255 * for a HeapMemMP instance will be greater than the size supplied here.
256 * Additional space will be consumed by shared instance attributes and
257 * alignment-related padding. Use the {@link #sharedMemReq} or the
258 * {@link #sharedMemReqMeta} call to determine the exact amount of shared
259 * memory required for an instance for a given sharedBufSize and cache
260 * settings.
261 */
262 config SizeT sharedBufSize = 0;
263
264 /*!
265 * ======== getStats ========
266 * @a(HeapMemMP)
267 * getStats() will lock the heap using the HeapMemMP Gate while it retrieves
268 * the HeapMemMP's statistics.
269 *
270 * The returned totalSize reflects the usable size of the buffer, not
271 * necessarily the size specified during create.
272 */
273 override Void getStats(xdc.runtime.Memory.Stats *stats);
274
275 internal:
276
277 /*! Used in the attrs->status field */
278 const UInt32 CREATED = 0x07041776;
279
280 /*!
281 * This Params object is used for temporary storage of the
282 * module wide parameters that are for setting the NameServer instance.
283 */
284 metaonly config NameServer.Params nameSrvPrms;
285
286 /*! Initialize shared memory, adjust alignment, allocate memory for buf */
287 Void postInit(Object *obj, Error.Block *eb);
288
289 /*!
290 * Header maintained at the lower address of every free block. The size of
291 * this struct must be a power of 2
292 */
293 struct Header {
294 SharedRegion.SRPtr next;
295 Bits32 size;
296 };
297
298 /*! Structure of attributes in shared memory */
299 struct Attrs {
300 Bits32 status;
301 SharedRegion.SRPtr bufPtr;
302 Header head;
303
304
305 SharedRegion.SRPtr gateMPAddr;
306 }
307
308 struct Instance_State {
309 Attrs *attrs;
310 GateMP.Handle gate;
311 Ipc.ObjType objType;
312 Ptr nsKey;
313 Bool cacheEnabled;
314 UInt32 regionId;
315 SizeT allocSize;
316 Char *buf;
317 SizeT minAlign;
318 SizeT bufSize;
319 };
320
321 struct Module_State {
322 NameServer.Handle nameServer;
323 };
324 }
325