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