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