1 /* Copyright (c) 2008-2011 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 *//***************************************************************************/ 88 t_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 *//***************************************************************************/ 118 uint64_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 *//***************************************************************************/ 129 uint64_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 *//***************************************************************************/ 149 uint64_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 *//***************************************************************************/ 184 uint64_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 *//***************************************************************************/ 209 uint64_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 *//***************************************************************************/ 226 uint64_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 *//***************************************************************************/ 243 t_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 into the file. 249 250 @Param[in] h_MM - Handle to the MM object. 251 @Param[in] buff - A pointer to a buffer 252 *//***************************************************************************/ 253 void MM_Dump(t_Handle h_MM, void *buff); 254 255 /**************************************************************************//** 256 @Function MM_Free 257 258 @Description Releases memory allocated for MM object. 259 260 @Param[in] h_MM - Handle of the MM object. 261 *//***************************************************************************/ 262 void MM_Free(t_Handle h_MM); 263 264 /**************************************************************************//** 265 @Function MM_GetMemBlock 266 267 @Description Returns base address of the memory block specified by the index. 268 269 If index is 0, returns base address 270 of the first memory block, 1 - returns base address 271 of the second memory block, etc. 272 Note, those memory blocks are allocated by the 273 application before MM_Init or MM_Add and have to 274 be released by the application before or after invoking 275 the MM_Free routine. 276 277 @Param[in] h_MM - Handle to the MM object. 278 @Param[in] index - Index of the memory block. 279 280 @Return valid base address or ILLEGAL_BASE if no memory block specified by the index. 281 *//***************************************************************************/ 282 uint64_t MM_GetMemBlock(t_Handle h_MM, int index); 283 284 /**************************************************************************//** 285 @Function MM_InRange 286 287 @Description Checks if a specific address is in the memory range of the passed MM object. 288 289 @Param[in] h_MM - Handle to the MM object. 290 @Param[in] addr - The address to be checked. 291 292 @Return TRUE if the address is in the address range of the block, FALSE otherwise. 293 *//***************************************************************************/ 294 bool MM_InRange(t_Handle h_MM, uint64_t addr); 295 296 297 /** @} */ /* end of mm_grp group */ 298 /** @} */ /* end of etc_id group */ 299 300 #endif /* __MM_EXT_H */ 301