xref: /freebsd/sys/contrib/ncsw/inc/etc/mm_ext.h (revision dd41de95a84d979615a2ef11df6850622bf6184e)
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 *//***************************************************************************/
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.
249 
250  @Param[in]     h_MM        - Handle to the MM object.
251 *//***************************************************************************/
252 void        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 *//***************************************************************************/
261 void        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 *//***************************************************************************/
281 uint64_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 *//***************************************************************************/
293 bool        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 *//***************************************************************************/
304 uint64_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