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/HeapMemMP.h
34 *
35 * @brief Multi-processor variable size buffer heap implementation
36 *
37 * @note HeapMemMP is currently only available for SYS/BIOS.
38 *
39 * HeapMemMP is a heap implementation that manages variable size buffers that
40 * can be used in a multiprocessor system with shared memory. HeapMemMP
41 * manages a single buffer in shared memory from which blocks of user-
42 * specified length are allocated and freed.
43 *
44 * The HeapMemMP module uses a NameServer instance to
45 * store instance information when an instance is created. The name supplied
46 * must be unique for all HeapMemMP instances.
47 *
48 * HeapMemMP_create() initializes the shared memory as needed. Once an
49 * instance is created, HeapMemMP_open() can be called. The
50 * open is used to gain access to the same HeapMemMP instance.
51 * Generally an instance is created on one processor and opened on the
52 * other processor(s).
53 *
54 * The open returns a HeapMemMP instance handle like the create,
55 * however the open does not modify the shared memory.
56 *
57 * Because HeapMemMP is a variable-size heap implementation, it is also used
58 * by the SharedRegion module to manage shared memory in each shared
59 * region. When any shared memory IPC instance is created in a
60 * particular shared region, the HeapMemMP that manages shared memory in the
61 * shared region allocates shared memory for the instance.
62 *
63 * The HeapMemMP header should be included in an application as follows:
64 * @code
65 * #include <ti/ipc/HeapMemMP.h>
66 * @endcode
67 */
69 #ifndef ti_ipc_HeapMemMP__include
70 #define ti_ipc_HeapMemMP__include
72 #if defined (__cplusplus)
73 extern "C" {
74 #endif
76 #include <ti/ipc/GateMP.h>
78 /* =============================================================================
79 * All success and failure codes for the module
80 * =============================================================================
81 */
83 /*!
84 * @brief The resource is still in use
85 */
86 #define HeapMemMP_S_BUSY 2
88 /*!
89 * @brief The module has been already setup
90 */
91 #define HeapMemMP_S_ALREADYSETUP 1
93 /*!
94 * @brief Operation is successful.
95 */
96 #define HeapMemMP_S_SUCCESS 0
98 /*!
99 * @brief Generic failure.
100 */
101 #define HeapMemMP_E_FAIL -1
103 /*!
104 * @brief Argument passed to function is invalid.
105 */
106 #define HeapMemMP_E_INVALIDARG -2
108 /*!
109 * @brief Operation resulted in memory failure.
110 */
111 #define HeapMemMP_E_MEMORY -3
113 /*!
114 * @brief The specified entity already exists.
115 */
116 #define HeapMemMP_E_ALREADYEXISTS -4
118 /*!
119 * @brief Unable to find the specified entity.
120 */
121 #define HeapMemMP_E_NOTFOUND -5
123 /*!
124 * @brief Operation timed out.
125 */
126 #define HeapMemMP_E_TIMEOUT -6
128 /*!
129 * @brief Module is not initialized.
130 */
131 #define HeapMemMP_E_INVALIDSTATE -7
133 /*!
134 * @brief A failure occurred in an OS-specific call */
135 #define HeapMemMP_E_OSFAILURE -8
137 /*!
138 * @brief Specified resource is not available */
139 #define HeapMemMP_E_RESOURCE -9
141 /*!
142 * @brief Operation was interrupted. Please restart the operation */
143 #define HeapMemMP_E_RESTART -10
145 /* =============================================================================
146 * Structures & Enums
147 * =============================================================================
148 */
150 /*!
151 * @brief HeapMemMP_Handle type
152 */
153 typedef struct HeapMemMP_Object *HeapMemMP_Handle;
155 /*!
156 * @brief Structure defining parameters for the HeapMemMP module.
157 *
158 * @sa HeapMemMP_create()
159 */
160 typedef struct HeapMemMP_Params {
161 String name;
162 /*!< Name of this instance.
163 *
164 * The name (if not NULL) must be unique among all HeapMemMP
165 * instances in the entire system. When creating a new
166 * heap, it is necessary to supply an instance name.
167 *
168 * The name does not have to be persistent. The supplied string is copied
169 * into persistent memory.
170 */
172 UInt16 regionId;
173 /*!< Shared region ID
174 *
175 * The index corresponding to the shared region from which shared memory
176 * will be allocated.
177 */
179 /*! @cond */
180 Ptr sharedAddr;
181 /*!< Physical address of the shared memory
182 *
183 * This value can be left as 'null' unless it is required to place the
184 * heap at a specific location in shared memory. If sharedAddr is null,
185 * then shared memory for a new instance will be allocated from the
186 * heap belonging to the region identified by #HeapMemMP_Params.regionId.
187 */
188 /*! @endcond */
190 SizeT sharedBufSize;
191 /*!< Size of shared buffer
192 *
193 * This is the size of the buffer to be used in the HeapMemMP instance.
194 * The actual buffer size in the created instance might actually be less
195 * than the value supplied in 'sharedBufSize' because of alignment
196 * constraints.
197 *
198 * It is important to note that the total amount of shared memory required
199 * for a HeapMemMP instance will be greater than the size supplied here.
200 * Additional space will be consumed by shared instance attributes and
201 * alignment-related padding.
202 */
204 GateMP_Handle gate;
205 /*!< GateMP used for critical region management of the shared memory
206 *
207 * Using the default value of NULL will result in use of the GateMP
208 * system gate for context protection.
209 */
211 } HeapMemMP_Params;
213 /*!
214 * @brief Stats structure for HeapMemMP_getExtendedStats()
215 *
216 * @sa HeapMemMP_getExtendedStats()
217 */
218 typedef struct HeapMemMP_ExtendedStats {
219 Ptr buf;
220 /*!< Local address of the shared buffer */
222 SizeT size;
223 /*!< Size of the shared buffer */
224 } HeapMemMP_ExtendedStats;
226 /* =============================================================================
227 * HeapMemMP Module-wide Functions
228 * =============================================================================
229 */
231 /*!
232 * @brief Close a HeapMemMP instance
233 *
234 * Closing an instance will free local memory consumed by the opened
235 * instance. All opened instances should be closed before the instance
236 * is deleted.
237 *
238 * @param[in,out] handlePtr Pointer to handle returned from
239 * HeapMemMP_open()
240 *
241 * @return HeapMemMP status:
242 * - #HeapMemMP_S_SUCCESS: Heap successfully closed
243 *
244 * @sa HeapMemMP_open()
245 */
246 Int HeapMemMP_close(HeapMemMP_Handle *handlePtr);
248 /*!
249 * @brief Create a HeapMemMP instance
250 *
251 * @param[in] params HeapMemMP parameters
252 *
253 * @return HeapMemMP Handle
254 *
255 * @sa HeapMemMP_delete()
256 */
257 HeapMemMP_Handle HeapMemMP_create(const HeapMemMP_Params *params);
259 /*!
260 * @brief Delete a created HeapMemMP instance
261 *
262 * @param[in,out] handlePtr Pointer to handle to delete.
263 *
264 * @return HeapMemMP status:
265 * - #HeapMemMP_S_SUCCESS: Heap successfully deleted
266 *
267 * @sa HeapMemMP_create()
268 */
269 Int HeapMemMP_delete(HeapMemMP_Handle *handlePtr);
271 /*!
272 * @brief Open a created HeapMemMP instance
273 *
274 * Once an instance is created, an open can be performed. The
275 * open is used to gain access to the same HeapMemMP instance.
276 * Generally an instance is created on one processor and opened on the
277 * other processor.
278 *
279 * The open returns a HeapMemMP instance handle like the create,
280 * however the open does not initialize the shared memory. The supplied
281 * name is used to identify the created instance.
282 *
283 * Call #HeapMemMP_close when the opened instance is not longer needed.
284 *
285 * @param[in] name Name of created HeapMemMP instance
286 * @param[out] handlePtr Pointer to HeapMemMP handle to be opened
287 *
288 * @return HeapMemMP status:
289 * - #HeapMemMP_S_SUCCESS: Heap successfully opened
290 * - #HeapMemMP_E_NOTFOUND: Heap is not yet ready to be opened.
291 * - #HeapMemMP_E_FAIL: A general failure has occurred
292 *
293 * @sa HeapMemMP_close
294 */
295 Int HeapMemMP_open(String name, HeapMemMP_Handle *handlePtr);
297 /*! @cond */
298 Int HeapMemMP_openByAddr(Ptr sharedAddr, HeapMemMP_Handle *handlePtr);
300 /*! @endcond */
302 /*!
303 * @brief Initialize a HeapMemMP parameters struct
304 *
305 * @param[out] params Pointer to creation parameters
306 *
307 * @sa HeapMemMP_create()
308 */
309 Void HeapMemMP_Params_init(HeapMemMP_Params *params);
311 /*! @cond */
312 /*!
313 * @brief Amount of shared memory required for creation of each instance
314 *
315 * @param[in] params Pointer to the parameters that will be used in
316 * the create.
317 *
318 * @return Number of MAUs needed to create the instance.
319 */
320 SizeT HeapMemMP_sharedMemReq(const HeapMemMP_Params *params);
322 /*! @endcond */
324 /* =============================================================================
325 * HeapMemMP Per-instance Functions
326 * =============================================================================
327 */
329 /*!
330 * @brief Allocate a block of memory of specified size and alignment
331 *
332 * The actual block returned may be larger than requested to satisfy
333 * alignment requirements. NULL is returned if the alloc fails.
334 *
335 * HeapMemMP_alloc will lock the heap using the HeapMemMP gate
336 * while it traverses the list of free blocks to find a large enough block
337 * for the request.
338 *
339 * Guidelines for using large heaps and multiple alloc() calls.
340 * - If possible, allocate larger blocks first. Previous allocations
341 * of small memory blocks can reduce the size of the blocks
342 * available for larger memory allocations.
343 * - Realize that allocation can fail even if the heap contains a
344 * sufficient absolute amount of unallocated space. This is
345 * because the largest free memory block may be smaller than
346 * total amount of unallocated memory.
347 *
348 * @param[in] handle Handle to previously created/opened instance.
349 * @param[in] size Size to be allocated (in MADUs)
350 * @param[in] align Alignment for allocation (power of 2)
351 *
352 * @sa HeapMemMP_free()
353 */
354 Void *HeapMemMP_alloc(HeapMemMP_Handle handle, SizeT size, SizeT align);
356 /*!
357 * @brief Frees a block of memory.
358 *
359 * HeapMemMP_free() places the memory block specified by addr and size back
360 * into the free pool of the heap specified. The newly freed block is combined
361 * with any adjacent free blocks. The space is then available for future
362 * allocations.
363 *
364 * HeapMemMP_free() will lock the heap using the HeapMemMP gate if one is
365 * specified or the system GateMP if not.
366 *
367 * @param[in] handle Handle to previously created/opened instance.
368 * @param[in] block Block of memory to be freed.
369 * @param[in] size Size to be freed (in MADUs)
370 *
371 * @sa HeapMemMP_alloc()
372 */
373 Void HeapMemMP_free(HeapMemMP_Handle handle, Ptr block, SizeT size);
375 /*!
376 * @brief Get extended memory statistics
377 *
378 * This function retrieves extended statistics for a HeapMemMP
379 * instance. Refer to #HeapMemMP_ExtendedStats for more information
380 * regarding what information is returned.
381 *
382 * @param[in] handle Handle to previously created/opened instance.
383 * @param[out] stats ExtendedStats structure
384 *
385 * @sa HeapMemMP_getStats
386 */
387 Void HeapMemMP_getExtendedStats(HeapMemMP_Handle handle,
388 HeapMemMP_ExtendedStats *stats);
390 /*!
391 * @brief Get memory statistics
392 *
393 * @param[in] handle Handle to previously created/opened instance.
394 * @param[out] stats Memory statistics structure
395 *
396 * @sa HeapMemMP_getExtendedStats()
397 */
398 Void HeapMemMP_getStats(HeapMemMP_Handle handle, Ptr stats);
400 /*!
401 * @brief Restore an instance to it's original created state.
402 *
403 * This function restores an instance to
404 * its original created state. Any memory previously allocated from the
405 * heap is no longer valid after this API is called. This function
406 * does not check whether there is allocated memory or not.
407 *
408 * @param[in] handle Handle to previously created/opened instance.
409 */
410 Void HeapMemMP_restore(HeapMemMP_Handle handle);
412 #if defined (__cplusplus)
413 }
414 #endif /* defined (__cplusplus) */
415 #endif /* ti_ipc_HeapMemMP__include */