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