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