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