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.ListMP;
40 import ti.sdo.ipc.SharedRegion;
41 import ti.sdo.ipc.Ipc;
42 import ti.sdo.ipc.GateMP;
43 import ti.sdo.utils.NameServer;
44
45 import xdc.rov.ViewInfo;
46
47 import xdc.runtime.Error;
48 import xdc.runtime.Assert;
49
50 /*!
51 * ======== HeapBufMP ========
52 * Multi-processor fixed-size buffer heap implementation
53 *
54 * @p(html)
55 * This module has a common header that can be found in the {@link ti.ipc}
56 * package. Application code should include the common header file (not the
57 * RTSC-generated one):
58 *
59 * <PRE>#include <ti/ipc/HeapBufMP.h></PRE>
60 *
61 * The RTSC module must be used in the application's RTSC configuration file
62 * (.cfg) if runtime APIs will be used in the application:
63 *
64 * <PRE>HeapBufMP = xdc.useModule('ti.sdo.ipc.heaps.HeapBufMP');</PRE>
65 *
66 * Documentation for all runtime APIs, instance configuration parameters,
67 * error codes macros and type definitions available to the application
68 * integrator can be found in the
69 * <A HREF="../../../../../doxygen/html/files.html">Doxygen documenation</A>
70 * for the IPC product. However, the documentation presented on this page
71 * should be referred to for information specific to the RTSC module, such as
72 * module configuration, Errors, and Asserts.
73 * @p
74 *
75 * It is important to note that allocation tracking is disabled by default in
76 * {@link #trackAllocs}. Disabling allocation tracking improves alloc/free
77 * performance especially when cache calls are required in shared memory.
78 */
79
80 @InstanceInitError
81 @InstanceFinalize
82
83 module HeapBufMP inherits xdc.runtime.IHeap
84 {
85 /*! @_nodoc */
86 metaonly struct BasicView {
87 String name;
88 Ptr buf;
89 String objType;
90 Ptr gate;
91 Bool exact;
92 SizeT align;
93 SizeT blockSize;
94 UInt numBlocks;
95 UInt curAllocated;
96 UInt maxAllocated;
97 Ptr freeList;
98 }
99
100 /*! @_nodoc */
101 @Facet
102 metaonly config ViewInfo.Instance rovViewInfo =
103 ViewInfo.create({
104 viewMap: [
105 [
106 'Basic',
107 {
108 type: ViewInfo.INSTANCE,
109 viewInitFxn: 'viewInitBasic',
110 structName: 'BasicView'
111 }
112 ]
113 ]
114 });
115
116 /*!
117 * Assert raised when freeing a block that is not in the buffer's range
118 */
119 config Assert.Id A_invBlockFreed =
120 {msg: "A_invBlockFreed: Invalid block being freed"};
121
122 /*!
123 * Assert raised when freeing a block that isn't aligned properly
124 */
125 config Assert.Id A_badAlignment =
126 {msg: "A_badAlignment: Block being freed is not aligned properly "};
127
128 /*!
129 * Error raised when a requested alloc size is too large
130 */
131 config Error.Id E_sizeTooLarge =
132 {msg: "E_sizeTooLarge: Requested alloc size of %u is greater than %u"};
133
134 /*!
135 * Error raised when a requested alignment is too large
136 */
137 config Error.Id E_alignTooLarge =
138 {msg: "E_alignTooLarge: Requested alignment size of %u is greater than %u"};
139
140 /*!
141 * Error raised when exact matching failed
142 */
143 config Error.Id E_exactFail =
144 {msg: "E_exactFail: Exact allocation failed (requested size = %u and buffer size = %u)"};
145
146 /*!
147 * Error raised when there are no more blocks left in the buffer
148 */
149 config Error.Id E_noBlocksLeft =
150 {msg: "E_noBlocksLeft: No more blocks left in buffer (handle = 0x%x, requested size = %u)"};
151
152 /*!
153 * Maximum runtime entries
154 *
155 * Maximum number of HeapBufMP's that can be dynamically created and
156 * added to the NameServer.
157 *
158 * To minimize the amount of runtime allocation, this parameter allows
159 * the pre-allocation of memory for the HeapBufMP's NameServer table.
160 * The default is to allow growth (i.e. memory allocation when
161 * creating a new instance).
162 */
163 metaonly config UInt maxRuntimeEntries = NameServer.ALLOWGROWTH;
164
165 /*!
166 * Maximum length for heap names
167 */
168 config UInt maxNameLen = 32;
169
170 /*!
171 * Section name is used to place the names table
172 *
173 * The default value of NULL implies that no explicit placement is
174 * performed.
175 */
176 metaonly config String tableSection = null;
177
178 /*!
179 * Track the number of allocated blocks
180 *
181 * This will enable/disable the tracking of the current and maximum number
182 * of allocations for a HeapBufMP instance. This maximum refers to the
183 * "all time" maximum number of allocations for the history of a HeapBufMP
184 * instance.
185 *
186 * Tracking allocations might adversely affect performance when allocating
187 * and/or freeing. This is especially true if cache is enabled for the
188 * shared region. If this feature is not needed, setting this to false
189 * avoids the performance penalty.
190 */
191 config Bool trackAllocs = false;
192
193 instance:
194
195 /*!
196 * GateMP used for critical region management of the shared memory
197 *
198 * Using the default value of NULL will result in use of the GateMP
199 * system gate for context protection.
200 */
201 config GateMP.Handle gate = null;
202
203 /*! @_nodoc
204 * Set to TRUE by the open() call. No one else should touch this!
205 */
206 config Bool openFlag = false;
207
208 /*!
209 * Use exact matching
210 *
211 * Setting this flag will allow allocation only if the requested size
212 * is equal to (rather than less than or equal to) the buffer's block
213 * size.
214 */
215 config Bool exact = false;
216
217 /*!
218 * Name of this instance.
219 *
220 * The name (if not NULL) must be unique among all HeapBufMP
221 * instances in the entire system. When creating a new
222 * heap, it is necessary to supply an instance name.
223 */
224 config String name = null;
225
226 /*!
227 * Alignment (in MAUs) of each block.
228 *
229 * The alignment must be a power of 2. If the value 0 is specified,
230 * the value will be changed to meet the minimum structure alignment
231 * requirements (refer to
232 * {@link xdc.runtime.Memory#getMaxDefaultTypeAlign} and
233 * {@link xdc.runtime.Memory#getMaxDefaultTypeAlignMeta} and
234 * the cache alignment size of the region in which the heap will
235 * be placed. Therefore, the actual alignment may be larger.
236 *
237 * The default alignment is 0.
238 */
239 config SizeT align = 0;
240
241 /*!
242 * Number of fixed-size blocks.
243 *
244 * This is a required parameter for all new HeapBufMP instances.
245 */
246 config UInt numBlocks = 0;
247
248 /*!
249 * Size (in MAUs) of each block.
250 *
251 * HeapBufMP will round the blockSize up to the nearest multiple of the
252 * alignment, so the actual blockSize may be larger. When creating a
253 * HeapBufMP dynamically, this needs to be taken into account to determine
254 * the proper buffer size to pass in.
255 *
256 * Required parameter.
257 *
258 * The default size of the blocks is 0 MAUs.
259 */
260 config SizeT blockSize = 0;
261
262 /*!
263 * Shared region ID
264 *
265 * The index corresponding to the shared region from which shared memory
266 * will be allocated.
267 */
268 config UInt16 regionId = 0;
269
270 /*! @_nodoc
271 * Physical address of the shared memory
272 *
273 * This value can be left as 'null' unless it is required to place the
274 * heap at a specific location in shared memory. If sharedAddr is null,
275 * then shared memory for a new instance will be allocated from the
276 * heap belonging to the region identified by {@link #regionId}.
277 */
278 config Ptr sharedAddr = null;
279
280 @DirectCall
281 override Ptr alloc(SizeT size, SizeT align, xdc.runtime.Error.Block *eb);
282
283 @DirectCall
284 override Void free(Ptr block, SizeT size);
285
286 internal:
287
288 /*! Used in the attrs->status field */
289 const UInt32 CREATED = 0x05251995;
290
291 /*!
292 * This Params object is used for temporary storage of the
293 * module wide parameters that are for setting the NameServer instance.
294 */
295 metaonly config NameServer.Params nameSrvPrms;
296
297 /*! slice and dice the buffer */
298 Void postInit(Object *obj, Error.Block *eb);
299
300 /*! Structure of attributes in shared memory */
301 struct Attrs {
302 Bits32 status;
303 SharedRegion.SRPtr gateMPAddr;
304 SharedRegion.SRPtr bufPtr;
305 Bits32 numFreeBlocks;
306 Bits32 minFreeBlocks;
307 Bits32 blockSize;
308 Bits32 align;
309 Bits32 numBlocks;
310 Bits16 exact;
311 }
312
313 struct Instance_State {
314 Attrs *attrs;
315 GateMP.Handle gate;
316 Ipc.ObjType objType;
317 Ptr nsKey;
318 Bool cacheEnabled;
319 UInt16 regionId;
320 SizeT allocSize;
321 Char *buf;
322 ListMP.Handle freeList;
323 SizeT blockSize;
324 SizeT align;
325 UInt numBlocks;
326 Bool exact;
327 };
328
329 struct Module_State {
330 NameServer.Handle nameServer;
331 };
332 }