[processor-sdk/performance-audio-sr.git] / ipc_3_43_00_00_eng / docs / cdoc / ti / sdo / ipc / heaps / HeapBufMP-src.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2 <html><head><title>module ti.sdo.ipc.heaps.HeapBufMP</title>
3 <meta name="googlebot" content="noindex,nofollow">
4 <link rel="stylesheet" type="text/css" href="../../../../src.css"/>
5 </head>
6 <body>
7 <pre class=src>
8 1 <span class="comment">/*
9 </span> 2 <span class="comment"> * Copyright (c) 2012-2013, Texas Instruments Incorporated
10 </span> 3 <span class="comment"> * All rights reserved.
11 </span> 4 <span class="comment"> *
12 </span> 5 <span class="comment"> * Redistribution and use in source and binary forms, with or without
13 </span> 6 <span class="comment"> * modification, are permitted provided that the following conditions
14 </span> 7 <span class="comment"> * are met:
15 </span> 8 <span class="comment"> *
16 </span> 9 <span class="comment"> * * Redistributions of source code must retain the above copyright
17 </span> 10 <span class="comment"> * notice, this list of conditions and the following disclaimer.
18 </span> 11 <span class="comment"> *
19 </span> 12 <span class="comment"> * * Redistributions in binary form must reproduce the above copyright
20 </span> 13 <span class="comment"> * notice, this list of conditions and the following disclaimer in the
21 </span> 14 <span class="comment"> * documentation and/or other materials provided with the distribution.
22 </span> 15 <span class="comment"> *
23 </span> 16 <span class="comment"> * * Neither the name of Texas Instruments Incorporated nor the names of
24 </span> 17 <span class="comment"> * its contributors may be used to endorse or promote products derived
25 </span> 18 <span class="comment"> * from this software without specific prior written permission.
26 </span> 19 <span class="comment"> *
27 </span> 20 <span class="comment"> * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
28 </span> 21 <span class="comment"> * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
29 </span> 22 <span class="comment"> * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
30 </span> 23 <span class="comment"> * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
31 </span> 24 <span class="comment"> * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
32 </span> 25 <span class="comment"> * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
33 </span> 26 <span class="comment"> * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
34 </span> 27 <span class="comment"> * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
35 </span> 28 <span class="comment"> * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
36 </span> 29 <span class="comment"> * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
37 </span> 30 <span class="comment"> * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
38 </span> 31 <span class="comment"> */</span>
39 32 <span class="comment">/*
40 </span> 33 <span class="comment"> * ======== HeapBufMP.xdc ========
41 </span> 34 <span class="comment"> *
42 </span> 35 <span class="comment"> */</span>
43 36
44 37 <span class=key>package</span> ti.sdo.ipc.heaps;
45 38
46 39 import ti.sdo.ipc.ListMP;
47 40 import ti.sdo.ipc.SharedRegion;
48 41 import ti.sdo.ipc.Ipc;
49 42 import ti.sdo.ipc.GateMP;
50 43 import ti.sdo.utils.NameServer;
51 44
52 45 import xdc.rov.ViewInfo;
53 46
54 47 import xdc.runtime.Error;
55 48 import xdc.runtime.Assert;
56 49
57 50 <span class="xdoc">/*!
58 </span> 51 <span class="xdoc"> * ======== HeapBufMP ========
59 </span> 52 <span class="xdoc"> * Multi-processor fixed-size buffer heap implementation
60 </span> 53 <span class="xdoc"> *
61 </span> 54 <span class="xdoc"> * <b>@p(html)</b>
62 </span> 55 <span class="xdoc"> * This module has a common header that can be found in the {<b>@link</b> ti.ipc}
63 </span> 56 <span class="xdoc"> * package. Application code should include the common header file (not the
64 </span> 57 <span class="xdoc"> * RTSC-generated one):
65 </span> 58 <span class="xdoc"> *
66 </span> 59 <span class="xdoc"> * <PRE>#include &lt;ti/ipc/HeapBufMP.h&gt;</PRE>
67 </span> 60 <span class="xdoc"> *
68 </span> 61 <span class="xdoc"> * The RTSC module must be used in the application's RTSC configuration file
69 </span> 62 <span class="xdoc"> * (.cfg) if runtime APIs will be used in the application:
70 </span> 63 <span class="xdoc"> *
71 </span> 64 <span class="xdoc"> * <PRE>HeapBufMP = xdc.useModule('ti.sdo.ipc.heaps.HeapBufMP');</PRE>
72 </span> 65 <span class="xdoc"> *
73 </span> 66 <span class="xdoc"> * Documentation for all runtime APIs, instance configuration parameters,
74 </span> 67 <span class="xdoc"> * error codes macros and type definitions available to the application
75 </span> 68 <span class="xdoc"> * integrator can be found in the
76 </span> 69 <span class="xdoc"> * <A HREF="../../../../../doxygen/html/files.html">Doxygen documenation</A>
77 </span> 70 <span class="xdoc"> * for the IPC product. However, the documentation presented on this page
78 </span> 71 <span class="xdoc"> * should be referred to for information specific to the RTSC module, such as
79 </span> 72 <span class="xdoc"> * module configuration, Errors, and Asserts.
80 </span> 73 <span class="xdoc"> * <b>@p</b>
81 </span> 74 <span class="xdoc"> *
82 </span> 75 <span class="xdoc"> * It is important to note that allocation tracking is disabled by default in
83 </span> 76 <span class="xdoc"> * {<b>@link</b> #trackAllocs}. Disabling allocation tracking improves alloc/free
84 </span> 77 <span class="xdoc"> * performance especially when cache calls are required in shared memory.
85 </span> 78 <span class="xdoc"> */</span>
86 79
87 80 @InstanceInitError
88 81 @InstanceFinalize
89 82
90 83 <span class=key>module</span> HeapBufMP <span class=key>inherits</span> xdc.runtime.IHeap
91 84 {
92 85 <span class="xdoc">/*! <b>@_nodoc</b> */</span>
93 86 <span class=key>metaonly</span> <span class=key>struct</span> BasicView {
94 87 String name;
95 88 Ptr buf;
96 89 String objType;
97 90 Ptr gate;
98 91 Bool exact;
99 92 SizeT align;
100 93 SizeT blockSize;
101 94 UInt numBlocks;
102 95 UInt curAllocated;
103 96 UInt maxAllocated;
104 97 Ptr freeList;
105 98 }
106 99
107 100 <span class="xdoc">/*! <b>@_nodoc</b> */</span>
108 101 @Facet
109 102 <span class=key>metaonly</span> <span class=key>config</span> ViewInfo.Instance rovViewInfo =
110 103 ViewInfo.create({
111 104 viewMap: [
112 105 [
113 106 <span class="string">'Basic'</span>,
114 107 {
115 108 type: ViewInfo.INSTANCE,
116 109 viewInitFxn: <span class="string">'viewInitBasic'</span>,
117 110 structName: <span class="string">'BasicView'</span>
118 111 }
119 112 ]
120 113 ]
121 114 });
122 115
123 116 <span class="xdoc">/*!
124 </span> 117 <span class="xdoc"> * Assert raised when freeing a block that is not in the buffer's range
125 </span> 118 <span class="xdoc"> */</span>
126 119 <span class=key>config</span> Assert.Id A_invBlockFreed =
127 120 {msg: <span class="string">"A_invBlockFreed: Invalid block being freed"</span>};
128 121
129 122 <span class="xdoc">/*!
130 </span> 123 <span class="xdoc"> * Assert raised when freeing a block that isn't aligned properly
131 </span> 124 <span class="xdoc"> */</span>
132 125 <span class=key>config</span> Assert.Id A_badAlignment =
133 126 {msg: <span class="string">"A_badAlignment: Block being freed is not aligned properly "</span>};
134 127
135 128 <span class="xdoc">/*!
136 </span> 129 <span class="xdoc"> * Error raised when a requested alloc size is too large
137 </span> 130 <span class="xdoc"> */</span>
138 131 <span class=key>config</span> Error.Id E_sizeTooLarge =
139 132 {msg: <span class="string">"E_sizeTooLarge: Requested alloc size of %u is greater than %u"</span>};
140 133
141 134 <span class="xdoc">/*!
142 </span> 135 <span class="xdoc"> * Error raised when a requested alignment is too large
143 </span> 136 <span class="xdoc"> */</span>
144 137 <span class=key>config</span> Error.Id E_alignTooLarge =
145 138 {msg: <span class="string">"E_alignTooLarge: Requested alignment size of %u is greater than %u"</span>};
146 139
147 140 <span class="xdoc">/*!
148 </span> 141 <span class="xdoc"> * Error raised when exact matching failed
149 </span> 142 <span class="xdoc"> */</span>
150 143 <span class=key>config</span> Error.Id E_exactFail =
151 144 {msg: <span class="string">"E_exactFail: Exact allocation failed (requested size = %u and buffer size = %u)"</span>};
152 145
153 146 <span class="xdoc">/*!
154 </span> 147 <span class="xdoc"> * Error raised when there are no more blocks left in the buffer
155 </span> 148 <span class="xdoc"> */</span>
156 149 <span class=key>config</span> Error.Id E_noBlocksLeft =
157 150 {msg: <span class="string">"E_noBlocksLeft: No more blocks left in buffer (handle = 0x%x, requested size = %u)"</span>};
158 151
159 152 <span class="xdoc">/*!
160 </span> 153 <span class="xdoc"> * Maximum runtime entries
161 </span> 154 <span class="xdoc"> *
162 </span> 155 <span class="xdoc"> * Maximum number of HeapBufMP's that can be dynamically created and
163 </span> 156 <span class="xdoc"> * added to the NameServer.
164 </span> 157 <span class="xdoc"> *
165 </span> 158 <span class="xdoc"> * To minimize the amount of runtime allocation, this parameter allows
166 </span> 159 <span class="xdoc"> * the pre-allocation of memory for the HeapBufMP's NameServer table.
167 </span> 160 <span class="xdoc"> * The default is to allow growth (i.e. memory allocation when
168 </span> 161 <span class="xdoc"> * creating a new instance).
169 </span> 162 <span class="xdoc"> */</span>
170 163 <span class=key>metaonly</span> <span class=key>config</span> UInt maxRuntimeEntries = NameServer.ALLOWGROWTH;
171 164
172 165 <span class="xdoc">/*!
173 </span> 166 <span class="xdoc"> * Maximum length for heap names
174 </span> 167 <span class="xdoc"> */</span>
175 168 <span class=key>config</span> UInt maxNameLen = 32;
176 169
177 170 <span class="xdoc">/*!
178 </span> 171 <span class="xdoc"> * Section name is used to place the names table
179 </span> 172 <span class="xdoc"> *
180 </span> 173 <span class="xdoc"> * The default value of NULL implies that no explicit placement is
181 </span> 174 <span class="xdoc"> * performed.
182 </span> 175 <span class="xdoc"> */</span>
183 176 <span class=key>metaonly</span> <span class=key>config</span> String tableSection = <span class=key>null</span>;
184 177
185 178 <span class="xdoc">/*!
186 </span> 179 <span class="xdoc"> * Track the number of allocated blocks
187 </span> 180 <span class="xdoc"> *
188 </span> 181 <span class="xdoc"> * This will enable/disable the tracking of the current and maximum number
189 </span> 182 <span class="xdoc"> * of allocations for a HeapBufMP instance. This maximum refers to the
190 </span> 183 <span class="xdoc"> * "all time" maximum number of allocations for the history of a HeapBufMP
191 </span> 184 <span class="xdoc"> * instance.
192 </span> 185 <span class="xdoc"> *
193 </span> 186 <span class="xdoc"> * Tracking allocations might adversely affect performance when allocating
194 </span> 187 <span class="xdoc"> * and/or freeing. This is especially true if cache is enabled for the
195 </span> 188 <span class="xdoc"> * shared region. If this feature is not needed, setting this to false
196 </span> 189 <span class="xdoc"> * avoids the performance penalty.
197 </span> 190 <span class="xdoc"> */</span>
198 191 <span class=key>config</span> Bool trackAllocs = <span class=key>false</span>;
199 192
200 193 <span class=key>instance</span>:
201 194
202 195 <span class="xdoc">/*!
203 </span> 196 <span class="xdoc"> * GateMP used for critical region management of the shared memory
204 </span> 197 <span class="xdoc"> *
205 </span> 198 <span class="xdoc"> * Using the default value of NULL will result in use of the GateMP
206 </span> 199 <span class="xdoc"> * system gate for context protection.
207 </span> 200 <span class="xdoc"> */</span>
208 201 <span class=key>config</span> GateMP.Handle gate = <span class=key>null</span>;
209 202
210 203 <span class="xdoc">/*! <b>@_nodoc</b>
211 </span> 204 <span class="xdoc"> * Set to TRUE by the open() call. No one else should touch this!
212 </span> 205 <span class="xdoc"> */</span>
213 206 <span class=key>config</span> Bool openFlag = <span class=key>false</span>;
214 207
215 208 <span class="xdoc">/*!
216 </span> 209 <span class="xdoc"> * Use exact matching
217 </span> 210 <span class="xdoc"> *
218 </span> 211 <span class="xdoc"> * Setting this flag will allow allocation only if the requested size
219 </span> 212 <span class="xdoc"> * is equal to (rather than less than or equal to) the buffer's block
220 </span> 213 <span class="xdoc"> * size.
221 </span> 214 <span class="xdoc"> */</span>
222 215 <span class=key>config</span> Bool exact = <span class=key>false</span>;
223 216
224 217 <span class="xdoc">/*!
225 </span> 218 <span class="xdoc"> * Name of this instance.
226 </span> 219 <span class="xdoc"> *
227 </span> 220 <span class="xdoc"> * The name (if not NULL) must be unique among all HeapBufMP
228 </span> 221 <span class="xdoc"> * instances in the entire system. When creating a new
229 </span> 222 <span class="xdoc"> * heap, it is necessary to supply an instance name.
230 </span> 223 <span class="xdoc"> */</span>
231 224 <span class=key>config</span> String name = <span class=key>null</span>;
232 225
233 226 <span class="xdoc">/*!
234 </span> 227 <span class="xdoc"> * Alignment (in MAUs) of each block.
235 </span> 228 <span class="xdoc"> *
236 </span> 229 <span class="xdoc"> * The alignment must be a power of 2. If the value 0 is specified,
237 </span> 230 <span class="xdoc"> * the value will be changed to meet the minimum structure alignment
238 </span> 231 <span class="xdoc"> * requirements (refer to
239 </span> 232 <span class="xdoc"> * {<b>@link</b> xdc.runtime.Memory#getMaxDefaultTypeAlign} and
240 </span> 233 <span class="xdoc"> * {<b>@link</b> xdc.runtime.Memory#getMaxDefaultTypeAlignMeta} and
241 </span> 234 <span class="xdoc"> * the cache alignment size of the region in which the heap will
242 </span> 235 <span class="xdoc"> * be placed. Therefore, the actual alignment may be larger.
243 </span> 236 <span class="xdoc"> *
244 </span> 237 <span class="xdoc"> * The default alignment is 0.
245 </span> 238 <span class="xdoc"> */</span>
246 239 <span class=key>config</span> SizeT align = 0;
247 240
248 241 <span class="xdoc">/*!
249 </span> 242 <span class="xdoc"> * Number of fixed-size blocks.
250 </span> 243 <span class="xdoc"> *
251 </span> 244 <span class="xdoc"> * This is a required parameter for all new HeapBufMP instances.
252 </span> 245 <span class="xdoc"> */</span>
253 246 <span class=key>config</span> UInt numBlocks = 0;
254 247
255 248 <span class="xdoc">/*!
256 </span> 249 <span class="xdoc"> * Size (in MAUs) of each block.
257 </span> 250 <span class="xdoc"> *
258 </span> 251 <span class="xdoc"> * HeapBufMP will round the blockSize up to the nearest multiple of the
259 </span> 252 <span class="xdoc"> * alignment, so the actual blockSize may be larger. When creating a
260 </span> 253 <span class="xdoc"> * HeapBufMP dynamically, this needs to be taken into account to determine
261 </span> 254 <span class="xdoc"> * the proper buffer size to pass in.
262 </span> 255 <span class="xdoc"> *
263 </span> 256 <span class="xdoc"> * Required parameter.
264 </span> 257 <span class="xdoc"> *
265 </span> 258 <span class="xdoc"> * The default size of the blocks is 0 MAUs.
266 </span> 259 <span class="xdoc"> */</span>
267 260 <span class=key>config</span> SizeT blockSize = 0;
268 261
269 262 <span class="xdoc">/*!
270 </span> 263 <span class="xdoc"> * Shared region ID
271 </span> 264 <span class="xdoc"> *
272 </span> 265 <span class="xdoc"> * The index corresponding to the shared region from which shared memory
273 </span> 266 <span class="xdoc"> * will be allocated.
274 </span> 267 <span class="xdoc"> */</span>
275 268 <span class=key>config</span> UInt16 regionId = 0;
276 269
277 270 <span class="xdoc">/*! <b>@_nodoc</b>
278 </span> 271 <span class="xdoc"> * Physical address of the shared memory
279 </span> 272 <span class="xdoc"> *
280 </span> 273 <span class="xdoc"> * This value can be left as 'null' unless it is required to place the
281 </span> 274 <span class="xdoc"> * heap at a specific location in shared memory. If sharedAddr is null,
282 </span> 275 <span class="xdoc"> * then shared memory for a new instance will be allocated from the
283 </span> 276 <span class="xdoc"> * heap belonging to the region identified by {<b>@link</b> #regionId}.
284 </span> 277 <span class="xdoc"> */</span>
285 278 <span class=key>config</span> Ptr sharedAddr = <span class=key>null</span>;
286 279
287 280 @DirectCall
288 281 <span class=key>override</span> Ptr alloc(SizeT size, SizeT align, xdc.runtime.Error.Block *eb);
289 282
290 283 @DirectCall
291 284 <span class=key>override</span> Void free(Ptr block, SizeT size);
292 285
293 286 <span class=key>internal</span>:
294 287
295 288 <span class="xdoc">/*! Used in the attrs->status field */</span>
296 289 <span class=key>const</span> UInt32 CREATED = 0x05251995;
297 290
298 291 <span class="xdoc">/*!
299 </span> 292 <span class="xdoc"> * This Params object is used for temporary storage of the
300 </span> 293 <span class="xdoc"> * module wide parameters that are for setting the NameServer instance.
301 </span> 294 <span class="xdoc"> */</span>
302 295 <span class=key>metaonly</span> <span class=key>config</span> NameServer.Params nameSrvPrms;
303 296
304 297 <span class="xdoc">/*! slice and dice the buffer */</span>
305 298 Void postInit(Object *obj, Error.Block *eb);
306 299
307 300 <span class="xdoc">/*! Structure of attributes in shared memory */</span>
308 301 <span class=key>struct</span> Attrs {
309 302 Bits32 status;
310 303 SharedRegion.SRPtr gateMPAddr; <span class="comment">/* GateMP SRPtr (shm safe) */</span>
311 304 SharedRegion.SRPtr bufPtr; <span class="comment">/* Memory managed by instance */</span>
312 305 Bits32 numFreeBlocks; <span class="comment">/* Number of free blocks */</span>
313 306 Bits32 minFreeBlocks; <span class="comment">/* Min number of free blocks */</span>
314 307 Bits32 blockSize; <span class="comment">/* True size of each block */</span>
315 308 Bits32 align; <span class="comment">/* Alignment of each block */</span>
316 309 Bits32 numBlocks; <span class="comment">/* Number of individual blocks. */</span>
317 310 Bits16 exact; <span class="comment">/* For 'exact' allocation */</span>
318 311 }
319 312
320 313 <span class=key>struct</span> Instance_State {
321 314 Attrs *attrs;
322 315 GateMP.Handle gate; <span class="comment">/* Gate for critical regions */</span>
323 316 Ipc.ObjType objType; <span class="comment">/* See enum ObjType */</span>
324 317 Ptr nsKey; <span class="comment">/* Used to remove NS entry */</span>
325 318 Bool cacheEnabled; <span class="comment">/* Whether to do cache calls */</span>
326 319 UInt16 regionId; <span class="comment">/* SharedRegion index */</span>
327 320 SizeT allocSize; <span class="comment">/* Shared memory allocated */</span>
328 321 Char *buf; <span class="comment">/* Local pointer to buf */</span>
329 322 ListMP.Handle freeList; <span class="comment">/* List of free buffers */</span>
330 323 SizeT blockSize; <span class="comment">/* Adjusted blockSize */</span>
331 324 SizeT align; <span class="comment">/* Adjusted alignment */</span>
332 325 UInt numBlocks; <span class="comment">/* Number of blocks in buffer */</span>
333 326 Bool exact; <span class="comment">/* Exact match flag */</span>
334 327 };
335 328
336 329 <span class=key>struct</span> Module_State {
337 330 NameServer.Handle nameServer; <span class="comment">/* NameServer for this module */</span>
338 331 };
339 332 }
340 </pre>
341 </body></html>