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