1 /*---------------------------------------------------------------------------*
2
3 Copyright (C) Nintendo. All rights reserved.
4
5 These coded instructions, statements, and computer programs contain
6 proprietary information of Nintendo of America Inc. and/or Nintendo
7 Company Ltd., and are protected by Federal copyright law. They may
8 not be disclosed to third parties or copied or duplicated in any form,
9 in whole or in part, without the prior written consent of Nintendo.
10
11 *---------------------------------------------------------------------------*/
12 /*---------------------------------------------------------------------------*
13 Project: MEM library
14 File: expHeap.h
15 Programmers: Takano Makoto
16
17 Copyright (C) Nintendo. All rights reserved.
18
19 These coded instructions, statements, and computer programs contain
20 proprietary information of Nintendo of America Inc. and/or Nintendo
21 Company Ltd., and are protected by Federal copyright law. They may
22 not be disclosed to third parties or copied or duplicated in any form,
23 in whole or in part, without the prior written consent of Nintendo.
24 *---------------------------------------------------------------------------*/
25
26 #ifndef MEM_EXPHEAP_H__
27 #define MEM_EXPHEAP_H__
28
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32
33
34 #include <cafe/mem/heapCommon.h>
35
36 /* =======================================================================
37 Constant Definitions
38 ======================================================================== */
39
40 // Memory allocation direction.
41 enum
42 {
43 MEM_EXPHEAP_ALLOC_DIR_FRONT, // Allocate from the front.
44 MEM_EXPHEAP_ALLOC_DIR_REAR // Allocate from the back.
45 };
46
47 // Memory allocation mode.
48 enum
49 {
50 /*
51 If this attribute is set, you can allocate a memory block from the first empty memory region found with a size equal to or greater than the size of the memory block you are trying to allocate.
52
53
54 */
55 MEM_EXPHEAP_ALLOC_MODE_FIRST = 0,
56
57 /*
58 If this attribute is set, you can allocate a memory block from the first empty memory region found with the size closest to the size of the memory block you are trying to allocate.
59
60
61 */
62 MEM_EXPHEAP_ALLOC_MODE_NEAR = 1
63 };
64
65
66 /* =======================================================================
67 Type Definitions
68 ======================================================================== */
69
70 typedef struct MEMiExpHeapMBlockHead MEMiExpHeapMBlockHead;
71
72 // Header information for a memory block (22 bytes).
73 struct MEMiExpHeapMBlockHead
74 {
75 union // Attribute.
76 {
77 u32 val;
78 struct
79 {
80 u32 allocDir : 1; // Memory allocation direction.
81 u32 alignment : 23; // Alignment.
82 u32 groupID : 8; // Group ID.
83 }
84 fields;
85 }
86 attribute;
87
88 u32 blockSize; // Block size (data area only).
89
90 MEMiExpHeapMBlockHead* pMBHeadPrev; // Previous block.
91 MEMiExpHeapMBlockHead* pMBHeadNext; // Next block.
92
93 u16 signature; // Signature.
94 };
95
96 typedef struct MEMiExpMBlockList MEMiExpMBlockList;
97
98 // Memory block list.
99 struct MEMiExpMBlockList
100 {
101 MEMiExpHeapMBlockHead* head; // Pointer to the memory block linked to the header.
102 MEMiExpHeapMBlockHead* tail; // Pointer to the memory block linked to the tail of the expanded heap.
103 };
104
105 typedef struct MEMiExpHeapHead MEMiExpHeapHead;
106
107 // Header information for the expanded heap.
108 struct MEMiExpHeapHead
109 {
110 MEMiExpMBlockList mbFreeList; // Free list.
111 MEMiExpMBlockList mbUsedList; // Used list.
112
113 u16 groupID; // Current group ID (lower 8 bits only).
114
115 union // Attribute.
116 {
117 u16 val;
118 struct
119 {
120 u16 _reserved : 14;
121 u16 useMarginOfAlign : 1; // If this attribute value is set, it is generated when aligning.
122 // Reuses spaces in memory as empty regions.
123 u16 allocMode : 1; // Memory allocation mode.
124 }
125 fields;
126 }
127 feature;
128 };
129
130
131 // Callback function type called for every memory block.
132 typedef void (*MEMHeapVisitor)( void* memBlock, MEMHeapHandle heap, u32 userParam );
133
134
135 /* =======================================================================
136 Macro Functions
137 ======================================================================== */
138
139
140 /* =======================================================================
141 Function Prototypes
142 ======================================================================== */
143
144 void MEMiDumpExpHeap( MEMHeapHandle heap );
145
146
147 MEMHeapHandle MEMCreateExpHeapEx(
148 void* startAddress,
149 u32 size,
150 u16 optFlag );
151
152 void* MEMDestroyExpHeap( MEMHeapHandle heap );
153
154 void* MEMAllocFromExpHeapEx(
155 MEMHeapHandle heap,
156 u32 size,
157 int alignment );
158
159 u32 MEMResizeForMBlockExpHeap(
160 MEMHeapHandle heap,
161 void* memBlock,
162 u32 size );
163
164 void MEMFreeToExpHeap( MEMHeapHandle heap, void* memBlock );
165
166 u32 MEMGetTotalFreeSizeForExpHeap( MEMHeapHandle heap );
167
168 u32 MEMGetAllocatableSizeForExpHeapEx( MEMHeapHandle heap, int alignment );
169
170 BOOL MEMiIsEmptyExpHeap( MEMHeapHandle heap );
171
172 u16 MEMSetAllocModeForExpHeap( MEMHeapHandle heap, u16 mode );
173 u16 MEMGetAllocModeForExpHeap( MEMHeapHandle heap );
174
175 BOOL MEMUseMarginOfAlignmentForExpHeap( MEMHeapHandle heap, BOOL reuse );
176
177 u16 MEMSetGroupIDForExpHeap( MEMHeapHandle heap, u16 groupID );
178 u16 MEMGetGroupIDForExpHeap( MEMHeapHandle heap );
179
180 void MEMVisitAllocatedForExpHeap(
181 MEMHeapHandle heap,
182 MEMHeapVisitor visitor,
183 u32 userParam );
184
185
186 u32 MEMGetSizeForMBlockExpHeap( const void* memBlock );
187
188 u16 MEMGetGroupIDForMBlockExpHeap( const void* memBlock );
189
190 u16 MEMGetAllocDirForMBlockExpHeap( const void* memBlock );
191
192 u32 MEMAdjustExpHeap( MEMHeapHandle heap );
193
194
195 /* =======================================================================
196 Inline Functions
197 ======================================================================== */
198
199 /*---------------------------------------------------------------------------*
200 Name: MEMCreateExpHeap
201
202 Description: Creates an expanded heap.
203
204 Arguments: startAddress: Start address of the heap area.
205 size: Size of the heap area.
206
207 Returns: If the function succeeds, a handle for the created expanded heap is returned.
208 If the function fails, HEAP_INVALID_HANDLE is returned.
209 *---------------------------------------------------------------------------*/
210 static inline MEMHeapHandle
MEMCreateExpHeap(void * startAddress,u32 size)211 MEMCreateExpHeap(
212 void* startAddress,
213 u32 size
214 )
215 {
216 return MEMCreateExpHeapEx( startAddress, size, 0 );
217 }
218
219
220 /*---------------------------------------------------------------------------*
221 Name: MEMAllocFromExpHeap
222
223 Description: Allocates a memory block from the expanded heap.
224 The alignment of the memory block is 4-byte fixed.
225
226 Arguments: heap: Handle for the expanded heap.
227 size: Size of the memory block to allocate (in bytes).
228
229 Returns: Returns a pointer to the allocated memory block if the allocation was successful.
230
231 If the operation fails, NULL is returned.
232 *---------------------------------------------------------------------------*/
233 static inline void*
MEMAllocFromExpHeap(MEMHeapHandle heap,u32 size)234 MEMAllocFromExpHeap(
235 MEMHeapHandle heap,
236 u32 size
237 )
238 {
239 return MEMAllocFromExpHeapEx( heap, size, MEM_HEAP_DEFAULT_ALIGNMENT );
240 }
241
242 /*---------------------------------------------------------------------------*
243 Name: MEMGetAllocatableSizeForExpHeap
244
245 Description: Gets a memory block of the maximum allocatable size from the expanded heap.
246 The alignment of the memory block is 4-byte fixed.
247
248 Arguments: heap: Handle for the expanded heap.
249
250 Returns: Returns the maximum allocatable size from the expanded heap (in bytes).
251 *---------------------------------------------------------------------------*/
252 static inline u32
MEMGetAllocatableSizeForExpHeap(MEMHeapHandle heap)253 MEMGetAllocatableSizeForExpHeap( MEMHeapHandle heap )
254 {
255 return MEMGetAllocatableSizeForExpHeapEx( heap, MEM_HEAP_DEFAULT_ALIGNMENT );
256 }
257
258
259
260 //#if !defined(_DEBUG)
261
262 //#define MEMCheckExpHeap( heap, optFlag ) (TRUE)
263 //#define MEMCheckForMBlockExpHeap( memBlock, heap, optFlag ) (TRUE)
264
265 // #if !defined(_DEBUG)
266 //#else
267
268 BOOL MEMCheckExpHeap( MEMHeapHandle heap, u32 optFlag );
269
270 BOOL MEMCheckForMBlockExpHeap(
271 const void* memBlock,
272 MEMHeapHandle heap,
273 u32 optFlag );
274
275 // #if defined(_DEBUG)
276 //#endif
277
278
279
280 #ifdef __cplusplus
281 } /* extern "C" */
282 #endif
283
284 /* MEM_EXPHEAP_H__ */
285 #endif
286