1/* Copyright (c) 2008-2012 Freescale Semiconductor, Inc
2 * All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are met:
6 *     * Redistributions of source code must retain the above copyright
7 *       notice, this list of conditions and the following disclaimer.
8 *     * Redistributions in binary form must reproduce the above copyright
9 *       notice, this list of conditions and the following disclaimer in the
10 *       documentation and/or other materials provided with the distribution.
11 *     * Neither the name of Freescale Semiconductor nor the
12 *       names of its contributors may be used to endorse or promote products
13 *       derived from this software without specific prior written permission.
14 *
15 *
16 * ALTERNATIVELY, this software may be distributed under the terms of the
17 * GNU General Public License ("GPL") as published by the Free Software
18 * Foundation, either version 2 of that License or (at your option) any
19 * later version.
20 *
21 * THIS SOFTWARE IS PROVIDED BY Freescale Semiconductor ``AS IS'' AND ANY
22 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
23 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
24 * DISCLAIMED. IN NO EVENT SHALL Freescale Semiconductor BE LIABLE FOR ANY
25 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
26 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
27 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
28 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
30 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
32
33
34/**************************************************************************//**
35 @File          mm_ext.h
36
37 @Description   Memory Manager Application Programming Interface
38*//***************************************************************************/
39#ifndef __MM_EXT
40#define __MM_EXT
41
42#include "std_ext.h"
43
44#define MM_MAX_ALIGNMENT    20  /* Alignments from 2 to 128 are available
45                                   where maximum alignment defined as
46                                   MM_MAX_ALIGNMENT power of 2 */
47
48#define MM_MAX_NAME_LEN     32
49
50/**************************************************************************//**
51 @Group         etc_id   Utility Library Application Programming Interface
52
53 @Description   External routines.
54
55 @{
56*//***************************************************************************/
57
58/**************************************************************************//**
59 @Group         mm_grp Flexible Memory Manager
60
61 @Description   Flexible Memory Manager module functions,definitions and enums.
62                (All of the following functions,definitions and enums can be found in mm_ext.h)
63
64 @{
65*//***************************************************************************/
66
67
68/**************************************************************************//**
69 @Function      MM_Init
70
71 @Description   Initializes a new MM object.
72
73                It initializes a new memory block consisting of base address
74                and size of the available memory by calling to MemBlock_Init
75                routine. It is also initializes a new free block for each
76                by calling FreeBlock_Init routine, which is pointed to
77                the almost all memory started from the required alignment
78                from the base address and to the end of the memory.
79                The handle to the new MM object is returned via "MM"
80                argument (passed by reference).
81
82 @Param[in]     h_MM    - Handle to the MM object.
83 @Param[in]     base    - Base address of the MM.
84 @Param[in]     size    - Size of the MM.
85
86 @Return        E_OK is returned on success. E_NOMEMORY is returned if the new MM object or a new free block can not be initialized.
87*//***************************************************************************/
88t_Error     MM_Init(t_Handle *h_MM, uint64_t base, uint64_t size);
89
90/**************************************************************************//**
91 @Function      MM_Get
92
93 @Description   Allocates a block of memory according to the given size and the alignment.
94
95                The Alignment argument tells from which
96                free list allocate a block of memory. 2^alignment indicates
97                the alignment that the base address of the allocated block
98                should have. So, the only values 1, 2, 4, 8, 16, 32 and 64
99                are available for the alignment argument.
100                The routine passes through the specific free list of free
101                blocks and seeks for a first block that have anough memory
102                that  is required (best fit).
103                After the block is found and data is allocated, it calls
104                the internal MM_CutFree routine to update all free lists
105                do not include a just allocated block. Of course, each
106                free list contains a free blocks with the same alignment.
107                It is also creates a busy block that holds
108                information about an allocated block.
109
110 @Param[in]     h_MM        - Handle to the MM object.
111 @Param[in]     size        - Size of the MM.
112 @Param[in]     alignment   - Index as a power of two defines a required
113                              alignment (in bytes); Should be 1, 2, 4, 8, 16, 32 or 64
114 @Param[in]     name        - The name that specifies an allocated block.
115
116 @Return        base address of an allocated block ILLEGAL_BASE if can't allocate a block
117*//***************************************************************************/
118uint64_t    MM_Get(t_Handle h_MM, uint64_t size, uint64_t alignment, char *name);
119
120/**************************************************************************//**
121 @Function      MM_GetBase
122
123 @Description   Gets the base address of the required MM objects.
124
125 @Param[in]     h_MM - Handle to the MM object.
126
127 @Return        base address of the block.
128*//***************************************************************************/
129uint64_t    MM_GetBase(t_Handle h_MM);
130
131/**************************************************************************//**
132 @Function      MM_GetForce
133
134 @Description   Force memory allocation.
135
136                It means to allocate a block of memory of the given
137                size from the given base address.
138                The routine checks if the required block can be allocated
139                (that is it is free) and then, calls the internal MM_CutFree
140                routine to update all free lists do not include that block.
141
142 @Param[in]     h_MM    - Handle to the MM object.
143 @Param[in]     base    - Base address of the MM.
144 @Param[in]     size    - Size of the MM.
145 @Param[in]     name    - Name that specifies an allocated block.
146
147 @Return        base address of an allocated block, ILLEGAL_BASE if can't allocate a block.
148*//***************************************************************************/
149uint64_t    MM_GetForce(t_Handle h_MM, uint64_t base, uint64_t size, char *name);
150
151/**************************************************************************//**
152 @Function      MM_GetForceMin
153
154 @Description   Allocates a block of memory according to the given size, the alignment and minimum base address.
155
156                The Alignment argument tells from which
157                free list allocate a block of memory. 2^alignment indicates
158                the alignment that the base address of the allocated block
159                should have. So, the only values 1, 2, 4, 8, 16, 32 and 64
160                are available for the alignment argument.
161                The minimum baser address forces the location of the block
162                to be from a given address onward.
163                The routine passes through the specific free list of free
164                blocks and seeks for the first base address equal or smaller
165                than the required minimum address and end address larger than
166                than the required base + its size - i.e. that may contain
167                the required block.
168                After the block is found and data is allocated, it calls
169                the internal MM_CutFree routine to update all free lists
170                do not include a just allocated block. Of course, each
171                free list contains a free blocks with the same alignment.
172                It is also creates a busy block that holds
173                information about an allocated block.
174
175 @Param[in]     h_MM        - Handle to the MM object.
176 @Param[in]     size        - Size of the MM.
177 @Param[in]     alignment   - Index as a power of two defines a required
178                              alignment (in bytes); Should be 1, 2, 4, 8, 16, 32 or 64
179 @Param[in]     min         - The minimum base address of the block.
180 @Param[in]     name        - Name that specifies an allocated block.
181
182 @Return        base address of an allocated block,ILLEGAL_BASE if can't allocate a block.
183*//***************************************************************************/
184uint64_t    MM_GetForceMin(t_Handle h_MM,
185                           uint64_t size,
186                           uint64_t alignment,
187                           uint64_t min,
188                           char     *name);
189
190/**************************************************************************//**
191 @Function      MM_Put
192
193 @Description   Puts a block of memory of the given base address back to the memory.
194
195                It checks if there is a busy block with the
196                given base address. If not, it returns 0, that
197                means can't free a block. Otherwise, it gets parameters of
198                the busy block and after it updates lists of free blocks,
199                removes that busy block from the list by calling to MM_CutBusy
200                routine.
201                After that it calls to MM_AddFree routine to add a new free
202                block to the free lists.
203
204 @Param[in]     h_MM    - Handle to the MM object.
205 @Param[in]     base    - Base address of the MM.
206
207 @Return         The size of bytes released, 0 if failed.
208*//***************************************************************************/
209uint64_t    MM_Put(t_Handle h_MM, uint64_t base);
210
211/**************************************************************************//**
212 @Function      MM_PutForce
213
214 @Description   Releases a block of memory of the required size from the required base address.
215
216                First, it calls to MM_CutBusy routine
217                to cut a free block from the busy list. And then, calls to
218                MM_AddFree routine to add the free block to the free lists.
219
220 @Param[in]     h_MM    - Handle to the MM object.
221 @Param[in]     base    - Base address of of a block to free.
222 @Param[in]     size    - Size of a block to free.
223
224 @Return        The number of bytes released, 0 on failure.
225*//***************************************************************************/
226uint64_t    MM_PutForce(t_Handle h_MM, uint64_t base, uint64_t size);
227
228/**************************************************************************//**
229 @Function      MM_Add
230
231 @Description   Adds a new memory block for memory allocation.
232
233                When a new memory block is initialized and added to the
234                memory list, it calls to MM_AddFree routine to add the
235                new free block to the free lists.
236
237 @Param[in]     h_MM    - Handle to the MM object.
238 @Param[in]     base    - Base address of the memory block.
239 @Param[in]     size    - Size of the memory block.
240
241 @Return        E_OK on success, otherwise returns an error code.
242*//***************************************************************************/
243t_Error     MM_Add(t_Handle h_MM, uint64_t base, uint64_t size);
244
245/**************************************************************************//**
246 @Function      MM_Dump
247
248 @Description   Prints results of free and busy lists.
249
250 @Param[in]     h_MM        - Handle to the MM object.
251*//***************************************************************************/
252void        MM_Dump(t_Handle h_MM);
253
254/**************************************************************************//**
255 @Function      MM_Free
256
257 @Description   Releases memory allocated for MM object.
258
259 @Param[in]     h_MM - Handle of the MM object.
260*//***************************************************************************/
261void        MM_Free(t_Handle h_MM);
262
263/**************************************************************************//**
264 @Function      MM_GetMemBlock
265
266 @Description   Returns base address of the memory block specified by the index.
267
268                If index is 0, returns base address
269                of the first memory block, 1 - returns base address
270                of the second memory block, etc.
271                Note, those memory blocks are allocated by the
272                application before MM_Init or MM_Add and have to
273                be released by the application before or after invoking
274                the MM_Free routine.
275
276 @Param[in]     h_MM    - Handle to the MM object.
277 @Param[in]     index   - Index of the memory block.
278
279 @Return        valid base address or ILLEGAL_BASE if no memory block specified by the index.
280*//***************************************************************************/
281uint64_t    MM_GetMemBlock(t_Handle h_MM, int index);
282
283/**************************************************************************//**
284 @Function      MM_InRange
285
286 @Description   Checks if a specific address is in the memory range of the passed MM object.
287
288 @Param[in]     h_MM    - Handle to the MM object.
289 @Param[in]     addr    - The address to be checked.
290
291 @Return        TRUE if the address is in the address range of the block, FALSE otherwise.
292*//***************************************************************************/
293bool        MM_InRange(t_Handle h_MM, uint64_t addr);
294
295/**************************************************************************//**
296 @Function      MM_GetFreeMemSize
297
298 @Description   Returns the size (in bytes) of free memory.
299
300 @Param[in]     h_MM    - Handle to the MM object.
301
302 @Return        Free memory size in bytes.
303*//***************************************************************************/
304uint64_t MM_GetFreeMemSize(t_Handle h_MM);
305
306
307/** @} */ /* end of mm_grp group */
308/** @} */ /* end of etc_id group */
309
310#endif /* __MM_EXT_H */
311