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 ti/ipc/HeapBufMP.h
34 *
35 * @brief Multi-processor fixed-size buffer heap implementation
36 *
37 * @note HeapBufMP is currently only available for SYS/BIOS.
38 *
39 * Heap implementation that manages fixed size buffers that can be used
40 * in a multiprocessor system with shared memory.
41 *
42 * The HeapBufMP manager provides functions to allocate and free storage from a
43 * heap of type HeapBufMP which inherits from IHeap. HeapBufMP manages a single
44 * fixed-size buffer, split into equally sized allocatable blocks.
45 *
46 * The HeapBufMP manager is intended as a very fast memory
47 * manager which can only allocate blocks of a single size. It is ideal for
48 * managing a heap that is only used for allocating a single type of object,
49 * or for objects that have very similar sizes.
50 *
51 * The HeapBufMP module uses a NameServer instance to
52 * store instance information when an instance is created. The name supplied
53 * must be unique for all HeapBufMP instances.
54 *
55 * HeapBufMP_create() initializes the shared memory as needed. Once an
56 * instance is created, HeapBufMP_open() can be performed. The
57 * open is used to gain access to the same HeapBufMP instance.
58 * Generally an instance is created on one processor and opened on the
59 * other processor(s).
60 *
61 * The open returns a HeapBufMP instance handle like the create,
62 * however the open does not modify the shared memory.
63 *
64 * The HeapBufMP header should be included in an application as follows:
65 * @code
66 * #include <ti/ipc/HeapBufMP.h>
67 * @endcode
68 */
70 #ifndef ti_ipc_HeapBufMP__include
71 #define ti_ipc_HeapBufMP__include
73 #if defined (__cplusplus)
74 extern "C" {
75 #endif
77 #include <ti/ipc/GateMP.h>
79 /* =============================================================================
80 * All success and failure codes for the module
81 * =============================================================================
82 */
84 /*!
85 * @brief The resource is still in use
86 */
87 #define HeapBufMP_S_BUSY 2
89 /*!
90 * @brief The module has been already setup
91 */
92 #define HeapBufMP_S_ALREADYSETUP 1
94 /*!
95 * @brief Operation is successful.
96 */
97 #define HeapBufMP_S_SUCCESS 0
99 /*!
100 * @brief Generic failure.
101 */
102 #define HeapBufMP_E_FAIL -1
104 /*!
105 * @brief Argument passed to function is invalid.
106 */
107 #define HeapBufMP_E_INVALIDARG -2
109 /*!
110 * @brief Operation resulted in memory failure.
111 */
112 #define HeapBufMP_E_MEMORY -3
114 /*!
115 * @brief The specified entity already exists.
116 */
117 #define HeapBufMP_E_ALREADYEXISTS -4
119 /*!
120 * @brief Unable to find the specified entity.
121 */
122 #define HeapBufMP_E_NOTFOUND -5
124 /*!
125 * @brief Operation timed out.
126 */
127 #define HeapBufMP_E_TIMEOUT -6
129 /*!
130 * @brief Module is not initialized.
131 */
132 #define HeapBufMP_E_INVALIDSTATE -7
134 /*!
135 * @brief A failure occurred in an OS-specific call
136 */
137 #define HeapBufMP_E_OSFAILURE -8
139 /*!
140 * @brief Specified resource is not available
141 */
142 #define HeapBufMP_E_RESOURCE -9
144 /*!
145 * @brief Operation was interrupted. Please restart the operation
146 */
147 #define HeapBufMP_E_RESTART -10
149 /* =============================================================================
150 * Structures & Enums
151 * =============================================================================
152 */
154 /*!
155 * @brief HeapBufMP_Handle type
156 */
157 typedef struct HeapBufMP_Object *HeapBufMP_Handle;
159 /*!
160 * @brief Structure defining parameters for the HeapBufMP module
161 *
162 * @sa HeapBufMP_create()
163 */
164 typedef struct HeapBufMP_Params {
165 String name;
166 /*!< @brief Name of this instance.
167 *
168 * The name (if not NULL) must be unique among all HeapBufMP
169 * instances in the entire system. When creating a new
170 * heap, it is necessary to supply an instance name.
171 *
172 * The name does not have to be persistent. The supplied string is copied
173 * into persistent memory.
174 */
176 UInt16 regionId;
177 /*!< @brief Shared region ID
178 *
179 * The index corresponding to the shared region from which shared memory
180 * will be allocated.
181 */
183 /*! @cond */
184 Ptr sharedAddr;
185 /*!< @brief Physical address of the shared memory
186 *
187 * This value can be left as 'null' unless it is required to place the
188 * heap at a specific location in shared memory. If sharedAddr is null,
189 * then shared memory for a new instance will be allocated from the
190 * heap belonging to the region identified by #HeapBufMP_Params.regionId.
191 */
192 /*! @endcond */
194 SizeT blockSize;
195 /*!< @brief Size (in MAUs) of each block.
196 *
197 * HeapBufMP will round the blockSize up to the nearest multiple of the
198 * alignment, so the actual blockSize may be larger. When creating a
199 * HeapBufMP dynamically, this needs to be taken into account to determine
200 * the proper buffer size to pass in.
201 *
202 * Required parameter.
203 *
204 * The default size of the blocks is 0 MAUs.
205 */
207 UInt numBlocks;
208 /*!< @brief Number of fixed-size blocks.
209 *
210 * This is a required parameter for all new HeapBufMP instances.
211 */
213 SizeT align;
214 /*!< @brief Alignment (in MAUs) of each block.
215 *
216 * The alignment must be a power of 2. If the value 0 is specified,
217 * the value will be changed to meet minimum structure alignment
218 * requirements and the cache alignment size of the region in which the
219 * heap will be placed. Therefore, the actual alignment may be larger.
220 *
221 * The default alignment is 0.
222 */
224 Bool exact;
225 /*!< @brief Use exact matching
226 *
227 * Setting this flag will allow allocation only if the requested size
228 * is equal to (rather than less than or equal to) the buffer's block
229 * size.
230 */
232 GateMP_Handle gate;
233 /*!< @brief GateMP used for critical region management of the shared memory
234 *
235 * Using the default value of NULL will result in use of the GateMP
236 * system gate for context protection.
237 */
239 } HeapBufMP_Params;
241 /*!
242 * @brief Stats structure for HeapBufMP_getExtendedStats()
243 *
244 * @sa HeapBufMP_getExtendedStats()
245 */
246 typedef struct HeapBufMP_ExtendedStats {
247 UInt maxAllocatedBlocks;
248 /*!< The maximum number of blocks allocated from this heap at any point in
249 * time during the lifetime of this HeapBufMP instance.
250 */
252 UInt numAllocatedBlocks;
253 /*!< The total number of blocks currently allocated in this HeapBufMP
254 * instance.
255 */
256 } HeapBufMP_ExtendedStats;
258 /* =============================================================================
259 * HeapBufMP Module-wide Functions
260 * =============================================================================
261 */
263 /*!
264 * @brief Close a HeapBufMP instance
265 *
266 * Closing an instance will free local memory consumed by the opened
267 * instance. All opened instances should be closed before the instance
268 * is deleted.
269 *
270 * @param[in,out] handlePtr Pointer to handle returned from
271 * HeapBufMP_open()
272 *
273 * @return HeapBufMP status:
274 * - #HeapBufMP_S_SUCCESS: Heap successfully closed
275 *
276 * @sa HeapBufMP_open()
277 */
278 Int HeapBufMP_close(HeapBufMP_Handle *handlePtr);
280 /*!
281 * @brief Create a HeapBufMP instance
282 *
283 * @param[in] params HeapBufMP parameters
284 *
285 * @return HeapBufMP Handle
286 *
287 * @sa HeapBufMP_delete()
288 */
289 HeapBufMP_Handle HeapBufMP_create(const HeapBufMP_Params *params);
291 /*!
292 * @brief Delete a created HeapBufMP instance
293 *
294 * @param[in,out] handlePtr Pointer to handle to delete.
295 *
296 * @return HeapBufMP status:
297 * - #HeapBufMP_S_SUCCESS: Heap successfully deleted
298 *
299 * @sa HeapBufMP_create()
300 */
301 Int HeapBufMP_delete(HeapBufMP_Handle *handlePtr);
303 /*!
304 * @brief Open a created HeapBufMP instance
305 *
306 * Once an instance is created, an open can be performed. The
307 * open is used to gain access to the same HeapBufMP instance.
308 * Generally an instance is created on one processor and opened on the
309 * other processor.
310 *
311 * The open returns a HeapBufMP instance handle like the create,
312 * however the open does not initialize the shared memory. The supplied
313 * name is used to identify the created instance.
314 *
315 * Call #HeapBufMP_close when the opened instance is not longer needed.
316 *
317 * @param[in] name Name of created HeapBufMP instance
318 * @param[out] handlePtr Pointer to HeapBufMP handle to be opened
319 *
320 * @return HeapBufMP status:
321 * - #HeapBufMP_S_SUCCESS: Heap successfully opened
322 * - #HeapBufMP_E_NOTFOUND: Heap is not yet ready to be opened.
323 * - #HeapBufMP_E_FAIL: A general failure has occurred
324 *
325 * @sa HeapBufMP_close()
326 */
327 Int HeapBufMP_open(String name, HeapBufMP_Handle *handlePtr);
329 /*! @cond */
330 Int HeapBufMP_openByAddr(Ptr sharedAddr, HeapBufMP_Handle *handlePtr);
332 /*! @endcond */
334 /*!
335 * @brief Initialize a HeapBufMP parameters struct
336 *
337 * @param[out] params Pointer to creation parameters
338 *
339 * @sa HeapBufMP_create()
340 */
341 Void HeapBufMP_Params_init(HeapBufMP_Params *params);
343 /*! @cond */
344 /*!
345 * @brief Amount of shared memory required for creation of each instance
346 *
347 * @param[in] params Pointer to the parameters that will be used in
348 * the create.
349 *
350 * @return Number of MAUs needed to create the instance.
351 */
352 SizeT HeapBufMP_sharedMemReq(const HeapBufMP_Params *params);
354 /*! @endcond */
356 /* =============================================================================
357 * HeapBufMP Per-instance Functions
358 * =============================================================================
359 */
361 /*!
362 * @brief Allocate a block of memory of specified size and alignment
363 *
364 * The actual block returned may be larger than requested to satisfy
365 * alignment requirements. NULL is returned if the allocation fails.
366 *
367 * HeapBufMP_alloc() will lock the heap using the HeapBufMP gate
368 * while it traverses the list of free blocks to find a large enough block
369 * for the request.
370 *
371 * Guidelines for using large heaps and multiple alloc() calls.
372 * - If possible, allocate larger blocks first. Previous allocations
373 * of small memory blocks can reduce the size of the blocks
374 * available for larger memory allocations.
375 * - Realize that allocation can fail even if the heap contains a
376 * sufficient absolute amount of unallocated space. This is
377 * because the largest free memory block may be smaller than
378 * total amount of unallocated memory.
379 *
380 * @param[in] handle Handle to previously created/opened instance.
381 * @param[in] size Size to be allocated (in MADUs)
382 * @param[in] align Alignment for allocation (power of 2)
383 *
384 * @sa HeapBufMP_free()
385 */
386 Void *HeapBufMP_alloc(HeapBufMP_Handle handle, SizeT size, SizeT align);
388 /*!
389 * @brief Frees a block of memory.
390 *
391 * HeapBufMP_free() places the memory block specified by addr and size back
392 * into the free pool of the heap specified. The newly freed block is combined
393 * with any adjacent free blocks. The space is then available for future
394 * allocations.
395 *
396 * HeapBufMP_free() will lock the heap using the HeapBufMP gate if one is
397 * specified or the system GateMP if not.
398 *
399 * @param[in] handle Handle to previously created/opened instance.
400 * @param[in] block Block of memory to be freed.
401 * @param[in] size Size to be freed (in MADUs)
402 *
403 * @sa HeapBufMP_alloc()
404 */
405 Void HeapBufMP_free(HeapBufMP_Handle handle, Ptr block, SizeT size);
407 /*!
408 * @brief Get extended memory statistics
409 *
410 * This function retrieves extended statistics for a HeapBufMP
411 * instance. Refer to #HeapBufMP_ExtendedStats for more information
412 * regarding what information is returned.
413 *
414 * In SYS/BIOS, HeapBufMP.trackAllocs needs to be set to 'true' in the
415 * configuration to get meaningful extended stats.
416 *
417 * @param[in] handle Handle to previously created/opened instance.
418 * @param[out] stats ExtendedStats structure
419 *
420 * @sa HeapBufMP_getStats()
421 */
422 Void HeapBufMP_getExtendedStats(HeapBufMP_Handle handle,
423 HeapBufMP_ExtendedStats *stats);
425 /*!
426 * @brief Get memory statistics
427 *
428 * @param[in] handle Handle to previously created/opened instance.
429 * @param[out] stats Memory statistics structure
430 *
431 * @sa HeapBufMP_getExtendedStats()
432 */
433 Void HeapBufMP_getStats(HeapBufMP_Handle handle, Ptr stats);
435 #if defined (__cplusplus)
436 }
437 #endif /* defined (__cplusplus) */
438 #endif /* ti_ipc_HeapBufMP__include */