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 * Error raised when a requested alloc size is too large
124 */
125 config Error.Id E_sizeTooLarge =
126 {msg: "E_sizeTooLarge: Requested alloc size of 0x%x is greater than 0x%x"};
127
128 /*!
129 * Error raised when a requested alignment is too large
130 */
131 config Error.Id E_alignTooLarge =
132 {msg: "E_alignTooLarge: Requested alignment size of %d is greater than %d"};
133
134 /*!
135 * Error raised when exact matching failed
136 */
137 config Error.Id E_exactFail =
138 {msg: "E_exactFail: Exact allocation failed (requested size = 0x%x and buffer size = 0x%x)"};
139
140 /*!
141 * Maximum runtime entries
142 *
143 * Maximum number of HeapBufMP's that can be dynamically created and
144 * added to the NameServer.
145 *
146 * To minimize the amount of runtime allocation, this parameter allows
147 * the pre-allocation of memory for the HeapBufMP's NameServer table.
148 * The default is to allow growth (i.e. memory allocation when
149 * creating a new instance).
150 */
151 metaonly config UInt maxRuntimeEntries = NameServer.ALLOWGROWTH;
152
153 /*!
154 * Maximum length for heap names
155 */
156 config UInt maxNameLen = 32;
157
158 /*!
159 * Section name is used to place the names table
160 *
161 * The default value of NULL implies that no explicit placement is
162 * performed.
163 */
164 metaonly config String tableSection = null;
165
166 /*!
167 * Track the number of allocated blocks
168 *
169 * This will enable/disable the tracking of the current and maximum number
170 * of allocations for a HeapBufMP instance. This maximum refers to the
171 * "all time" maximum number of allocations for the history of a HeapBufMP
172 * instance.
173 *
174 * Tracking allocations might adversely affect performance when allocating
175 * and/or freeing. This is especially true if cache is enabled for the
176 * shared region. If this feature is not needed, setting this to false
177 * avoids the performance penalty.
178 */
179 config Bool trackAllocs = false;
180
181 instance:
182
183 /*!
184 * GateMP used for critical region management of the shared memory
185 *
186 * Using the default value of NULL will result in use of the GateMP
187 * system gate for context protection.
188 */
189 config GateMP.Handle gate = null;
190
191 /*! @_nodoc
192 * Set to TRUE by the open() call. No one else should touch this!
193 */
194 config Bool openFlag = false;
195
196 /*!
197 * Use exact matching
198 *
199 * Setting this flag will allow allocation only if the requested size
200 * is equal to (rather than less than or equal to) the buffer's block
201 * size.
202 */
203 config Bool exact = false;
204
205 /*!
206 * Name of this instance.
207 *
208 * The name (if not NULL) must be unique among all HeapBufMP
209 * instances in the entire system. When creating a new
210 * heap, it is necessary to supply an instance name.
211 */
212 config String name = null;
213
214 /*!
215 * Alignment (in MAUs) of each block.
216 *
217 * The alignment must be a power of 2. If the value 0 is specified,
218 * the value will be changed to meet the minimum structure alignment
219 * requirements (refer to
220 * {@link xdc.runtime.Memory#getMaxDefaultTypeAlign} and
221 * {@link xdc.runtime.Memory#getMaxDefaultTypeAlignMeta} and
222 * the cache alignment size of the region in which the heap will
223 * be placed. Therefore, the actual alignment may be larger.
224 *
225 * The default alignment is 0.
226 */
227 config SizeT align = 0;
228
229 /*!
230 * Number of fixed-size blocks.
231 *
232 * This is a required parameter for all new HeapBufMP instances.
233 */
234 config UInt numBlocks = 0;
235
236 /*!
237 * Size (in MAUs) of each block.
238 *
239 * HeapBufMP will round the blockSize up to the nearest multiple of the
240 * alignment, so the actual blockSize may be larger. When creating a
241 * HeapBufMP dynamically, this needs to be taken into account to determine
242 * the proper buffer size to pass in.
243 *
244 * Required parameter.
245 *
246 * The default size of the blocks is 0 MAUs.
247 */
248 config SizeT blockSize = 0;
249
250 /*!
251 * Shared region ID
252 *
253 * The index corresponding to the shared region from which shared memory
254 * will be allocated.
255 */
256 config UInt16 regionId = 0;
257
258 /*! @_nodoc
259 * Physical address of the shared memory
260 *
261 * This value can be left as 'null' unless it is required to place the
262 * heap at a specific location in shared memory. If sharedAddr is null,
263 * then shared memory for a new instance will be allocated from the
264 * heap belonging to the region identified by {@link #regionId}.
265 */
266 config Ptr sharedAddr = null;
267
268 internal:
269
270 /*! Used in the attrs->status field */
271 const UInt32 CREATED = 0x05251995;
272
273 /*!
274 * This Params object is used for temporary storage of the
275 * module wide parameters that are for setting the NameServer instance.
276 */
277 metaonly config NameServer.Params nameSrvPrms;
278
279 /*! slice and dice the buffer */
280 Void postInit(Object *obj, Error.Block *eb);
281
282 /*! Structure of attributes in shared memory */
283 struct Attrs {
284 Bits32 status;
285 SharedRegion.SRPtr gateMPAddr;
286 SharedRegion.SRPtr bufPtr;
287 Bits32 numFreeBlocks;
288 Bits32 minFreeBlocks;
289 Bits32 blockSize;
290 Bits32 align;
291 Bits32 numBlocks;
292 Bits16 exact;
293 }
294
295 struct Instance_State {
296 Attrs *attrs;
297 GateMP.Handle gate;
298 Ipc.ObjType objType;
299 Ptr nsKey;
300 Bool cacheEnabled;
301 UInt16 regionId;
302 SizeT allocSize;
303 Char *buf;
304 ListMP.Handle freeList;
305 SizeT blockSize;
306 SizeT align;
307 UInt numBlocks;
308 Bool exact;
309 };
310
311 struct Module_State {
312 NameServer.Handle nameServer;
313 };
314 }
315 316 317
318