1 /*
2 * Copyright (c) 2012-2013, Texas Instruments Incorporated
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
32 /** ============================================================================
33 * @file HeapBufMP.h
34 *
35 * @brief Multi-processor fixed-size buffer heap implementation
36 *
37 * Heap implementation that manages fixed size buffers that can be used
38 * in a multiprocessor system with shared memory.
39 *
40 * The HeapBufMP manager provides functions to allocate and free storage from a
41 * heap of type HeapBufMP which inherits from IHeap. HeapBufMP manages a single
42 * fixed-size buffer, split into equally sized allocatable blocks.
43 *
44 * The HeapBufMP manager is intended as a very fast memory
45 * manager which can only allocate blocks of a single size. It is ideal for
46 * managing a heap that is only used for allocating a single type of object,
47 * or for objects that have very similar sizes.
48 *
49 * The HeapBufMP module uses a NameServer instance to
50 * store instance information when an instance is created. The name supplied
51 * must be unique for all HeapBufMP instances.
52 *
53 * The #HeapBufMP_create call initializes the shared memory as needed. Once an
54 * instance is created, a #HeapBufMP_open can be performed. The
55 * open is used to gain access to the same HeapBufMP instance.
56 * Generally an instance is created on one processor and opened on the
57 * other processor(s).
58 *
59 * The open returns a HeapBufMP instance handle like the create,
60 * however the open does not modify the shared memory.
61 *
62 * The HeapBufMP header should be included in an application as follows:
63 * @code
64 * #include <ti/ipc/HeapBufMP.h>
65 * @endcode
66 *
67 * @version 0.00.01
68 */
71 #ifndef ti_ipc_HeapBufMP__include
72 #define ti_ipc_HeapBufMP__include
74 #if defined (__cplusplus)
75 extern "C" {
76 #endif
78 #include <ti/ipc/GateMP.h>
80 /* =============================================================================
81 * All success and failure codes for the module
82 * =============================================================================
83 */
85 /*!
86 * @def HeapBufMP_S_BUSY
87 * @brief The resource is still in use
88 */
89 #define HeapBufMP_S_BUSY 2
91 /*!
92 * @def HeapBufMP_S_ALREADYSETUP
93 * @brief The module has been already setup
94 */
95 #define HeapBufMP_S_ALREADYSETUP 1
97 /*!
98 * @def HeapBufMP_S_SUCCESS
99 * @brief Operation is successful.
100 */
101 #define HeapBufMP_S_SUCCESS 0
103 /*!
104 * @def HeapBufMP_E_FAIL
105 * @brief Generic failure.
106 */
107 #define HeapBufMP_E_FAIL -1
109 /*!
110 * @def HeapBufMP_E_INVALIDARG
111 * @brief Argument passed to function is invalid.
112 */
113 #define HeapBufMP_E_INVALIDARG -2
115 /*!
116 * @def HeapBufMP_E_MEMORY
117 * @brief Operation resulted in memory failure.
118 */
119 #define HeapBufMP_E_MEMORY -3
121 /*!
122 * @def HeapBufMP_E_ALREADYEXISTS
123 * @brief The specified entity already exists.
124 */
125 #define HeapBufMP_E_ALREADYEXISTS -4
127 /*!
128 * @def HeapBufMP_E_NOTFOUND
129 * @brief Unable to find the specified entity.
130 */
131 #define HeapBufMP_E_NOTFOUND -5
133 /*!
134 * @def HeapBufMP_E_TIMEOUT
135 * @brief Operation timed out.
136 */
137 #define HeapBufMP_E_TIMEOUT -6
139 /*!
140 * @def HeapBufMP_E_INVALIDSTATE
141 * @brief Module is not initialized.
142 */
143 #define HeapBufMP_E_INVALIDSTATE -7
145 /*!
146 * @def HeapBufMP_E_OSFAILURE
147 * @brief A failure occurred in an OS-specific call */
148 #define HeapBufMP_E_OSFAILURE -8
150 /*!
151 * @def HeapBufMP_E_RESOURCE
152 * @brief Specified resource is not available */
153 #define HeapBufMP_E_RESOURCE -9
155 /*!
156 * @def HeapBufMP_E_RESTART
157 * @brief Operation was interrupted. Please restart the operation */
158 #define HeapBufMP_E_RESTART -10
160 /* =============================================================================
161 * Structures & Enums
162 * =============================================================================
163 */
165 /*!
166 * @brief HeapBufMP_Handle type
167 */
168 typedef struct HeapBufMP_Object *HeapBufMP_Handle;
170 /*!
171 * @brief Structure defining parameters for the HeapBufMP module.
172 */
173 typedef struct HeapBufMP_Params {
174 String name;
175 /*!< Name of this instance.
176 *
177 * The name (if not NULL) must be unique among all HeapBufMP
178 * instances in the entire system. When creating a new
179 * heap, it is necessary to supply an instance name.
180 *
181 * The name does not have to be persistent. The supplied string is copied
182 * into persistent memory.
183 */
185 UInt16 regionId;
186 /*!< Shared region ID
187 *
188 * The index corresponding to the shared region from which shared memory
189 * will be allocated.
190 */
192 /*! @cond */
193 Ptr sharedAddr;
194 /*!< Physical address of the shared memory
195 *
196 * This value can be left as 'null' unless it is required to place the
197 * heap at a specific location in shared memory. If sharedAddr is null,
198 * then shared memory for a new instance will be allocated from the
199 * heap belonging to the region identified by #HeapBufMP_Params::regionId.
200 */
201 /*! @endcond */
203 SizeT blockSize;
204 /*!< Size (in MAUs) of each block.
205 *
206 * HeapBufMP will round the blockSize up to the nearest multiple of the
207 * alignment, so the actual blockSize may be larger. When creating a
208 * HeapBufMP dynamically, this needs to be taken into account to determine
209 * the proper buffer size to pass in.
210 *
211 * Required parameter.
212 *
213 * The default size of the blocks is 0 MAUs.
214 */
216 UInt numBlocks;
217 /*!<Number of fixed-size blocks.
218 *
219 * This is a required parameter for all new HeapBufMP instances.
220 */
222 SizeT align;
223 /*!< Alignment (in MAUs) of each block.
224 *
225 * The alignment must be a power of 2. If the value 0 is specified,
226 * the value will be changed to meet minimum structure alignment
227 * requirements and the cache alignment size of the region in which the
228 * heap will be placed. Therefore, the actual alignment may be larger.
229 *
230 * The default alignment is 0.
231 */
233 Bool exact;
234 /*!< Use exact matching
235 *
236 * Setting this flag will allow allocation only if the requested size
237 * is equal to (rather than less than or equal to) the buffer's block
238 * size.
239 */
241 GateMP_Handle gate;
242 /*!< GateMP used for critical region management of the shared memory
243 *
244 * Using the default value of NULL will result in use of the GateMP
245 * system gate for context protection.
246 */
248 } HeapBufMP_Params;
250 /*!
251 * @brief Stats structure for the HeapBufMP_getExtendedStats API.
252 */
253 typedef struct HeapBufMP_ExtendedStats {
254 UInt maxAllocatedBlocks;
255 /*!< The maximum number of blocks allocated from this heap at any point in
256 * time during the lifetime of this HeapBufMP instance.
257 */
259 UInt numAllocatedBlocks;
260 /*!< The total number of blocks currently allocated in this HeapBufMP
261 * instance.
262 */
263 } HeapBufMP_ExtendedStats;
265 /* =============================================================================
266 * HeapBufMP Module-wide Functions
267 * =============================================================================
268 */
270 /*!
271 * @brief Close a HeapBufMP instance
272 *
273 * Closing an instance will free local memory consumed by the opened
274 * instance. All opened instances should be closed before the instance
275 * is deleted.
276 *
277 * @param[in,out] handlePtr Pointer to HeapBufMP handle typically returned
278 * from #HeapBufMP_open
279 *
280 * @return HeapBufMP status:
281 * - #HeapBufMP_S_SUCCESS: Heap successfully closed
282 *
283 * @sa HeapBufMP_open
284 */
285 Int HeapBufMP_close(HeapBufMP_Handle *handlePtr);
287 /*!
288 * @brief Create a HeapBufMP instance
289 *
290 * @param[in] params HeapBufMP parameters
291 *
292 * @return HeapBufMP Handle
293 */
294 HeapBufMP_Handle HeapBufMP_create(const HeapBufMP_Params *params);
296 /*!
297 * @brief Delete a created HeapBufMP instance
298 *
299 * @param[in,out] handlePtr Pointer to handle to delete.
300 *
301 * @return HeapBufMP status:
302 * - #HeapBufMP_S_SUCCESS: Heap successfully deleted
303 */
304 Int HeapBufMP_delete(HeapBufMP_Handle *handlePtr);
306 /*!
307 * @brief Open a created HeapBufMP instance
308 *
309 * Once an instance is created, an open can be performed. The
310 * open is used to gain access to the same HeapBufMP instance.
311 * Generally an instance is created on one processor and opened on the
312 * other processor.
313 *
314 * The open returns a HeapBufMP instance handle like the create,
315 * however the open does not initialize the shared memory. The supplied
316 * name is used to identify the created instance.
317 *
318 * Call #HeapBufMP_close when the opened instance is not longer needed.
319 *
320 * @param[in] name Name of created HeapBufMP instance
321 * @param[out] handlePtr Pointer to HeapBufMP handle to be opened
322 *
323 * @return HeapBufMP status:
324 * - #HeapBufMP_S_SUCCESS: Heap successfully opened
325 * - #HeapBufMP_E_NOTFOUND: Heap is not yet ready to be opened.
326 * - #HeapBufMP_E_FAIL: A general failure has occurred
327 *
328 * @sa HeapBufMP_close
329 */
330 Int HeapBufMP_open(String name, HeapBufMP_Handle *handlePtr);
332 /*! @cond */
333 Int HeapBufMP_openByAddr(Ptr sharedAddr, HeapBufMP_Handle *handlePtr);
335 /*! @endcond */
337 /*!
338 * @brief Initialize a HeapBufMP parameters struct
339 *
340 * @param[out] params Pointer to GateMP parameters
341 *
342 */
343 Void HeapBufMP_Params_init(HeapBufMP_Params *params);
345 /*! @cond */
346 /*!
347 * @brief Amount of shared memory required for creation of each instance
348 *
349 * @param[in] params Pointer to the parameters that will be used in
350 * the create.
351 *
352 * @return Number of MAUs needed to create the instance.
353 */
354 SizeT HeapBufMP_sharedMemReq(const HeapBufMP_Params *params);
356 /*! @endcond */
358 /* =============================================================================
359 * HeapBufMP Per-instance Functions
360 * =============================================================================
361 */
363 /*!
364 * @brief Allocate a block of memory of specified size and alignment
365 *
366 * The actual block returned may be larger than requested to satisfy
367 * alignment requirements. NULL is returned if alloc fails.
368 *
369 * HeapBufMP_alloc will lock the heap using the HeapBufMP gate
370 * while it traverses the list of free blocks to find a large enough block
371 * for the request.
372 *
373 * Guidelines for using large heaps and multiple alloc() calls.
374 * - If possible, allocate larger blocks first. Previous allocations
375 * of small memory blocks can reduce the size of the blocks
376 * available for larger memory allocations.
377 * - Realize that alloc() can fail even if the heap contains a
378 * sufficient absolute amount of unalloccated space. This is
379 * because the largest free memory block may be smaller than
380 * total amount of unallocated memory.
381 *
382 * @param[in] handle Handle to previously created/opened instance.
383 * @param[in] size Size to be allocated (in MADUs)
384 * @param[in] align Alignment for allocation (power of 2)
385 *
386 * @sa HeapBufMP_free
387 */
388 Void *HeapBufMP_alloc(HeapBufMP_Handle handle, SizeT size, SizeT align);
390 /*!
391 * @brief Frees a block of memory.
392 *
393 * free() places the memory block specified by addr and size back into the
394 * free pool of the heap specified. The newly freed block is combined with
395 * any adjacent free blocks. The space is then available for further
396 * allocation by alloc().
397 *
398 * #HeapBufMP_free will lock the heap using the HeapBufMP gate if one is
399 * specified or the system GateMP if not.
400 *
401 * @param[in] handle Handle to previously created/opened instance.
402 * @param[in] block Block of memory to be freed.
403 * @param[in] size Size to be freed (in MADUs)
404 *
405 * @sa HeapBufMP_alloc
406 */
407 Void HeapBufMP_free(HeapBufMP_Handle handle, Ptr block, SizeT size);
409 /*!
410 * @brief Get extended memory statistics
411 *
412 * This function retrieves the extended statistics for a HeapBufMP
413 * instance. It does not retrieve the standard Memory_Stats
414 * information. Refer to #HeapBufMP_ExtendedStats for more information
415 * regarding what information is returned.
416 *
417 * In BIOS, HeapBufMP.trackAllocs needs to be set to 'true' in the
418 * configuration to get meaningful extended stats.
419 *
420 * @param[in] handle Handle to previously created/opened instance.
421 * @param[out] stats ExtendedStats structure
422 *
423 * @sa HeapBufMP_getStats
424 */
425 Void HeapBufMP_getExtendedStats(HeapBufMP_Handle handle,
426 HeapBufMP_ExtendedStats *stats);
428 /*!
429 * @brief Get memory statistics
430 *
431 * @param[in] handle Handle to previously created/opened instance.
432 * @param[out] stats Memory statistics structure
433 *
434 * @sa HeapBufMP_getExtendedStats
435 */
436 Void HeapBufMP_getStats(HeapBufMP_Handle handle, Ptr stats);
438 #if defined (__cplusplus)
439 }
440 #endif /* defined (__cplusplus) */
441 #endif /* ti_ipc_HeapBufMP__include */