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: heapCommon.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 #ifndef MEM_HEAPCOMMON_H__
26 #define MEM_HEAPCOMMON_H__
27
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31
32
33 #include <types.h>
34 #include <cafe/os.h>
35 #include <cafe/mp.h>
36 #include <cafe/mem/list.h>
37
38
39 /* ========================================================================
40 Macro Constants
41 ======================================================================== */
42
43 // Invalid heap handle.
44 #define MEM_HEAP_INVALID_HANDLE NULL
45
46 // Default alignment size when memory is allocated from the heap.
47 #define MEM_HEAP_DEFAULT_ALIGNMENT 4
48
49
50 /* ------------------------------------------------------------------------
51 Fill Constants
52 ------------------------------------------------------------------------ */
53
54 // Zero out temporarily allocated memory.
55 #define MEM_HEAP_OPT_0_CLEAR (1 << 0)
56
57 // Temporary memory fill when a heap is created or new E memory is allocated or freed.
58 #define MEM_HEAP_OPT_DEBUG_FILL (1 << 1)
59
60 // Presence or absence of a locking mechanism.
61 #define MEM_HEAP_OPT_THREAD_SAFE (1 << 2)
62
63
64 /* ------------------------------------------------------------------------
65 Heap Check Constants
66 ------------------------------------------------------------------------ */
67 // If this bit stands, output the error.
68 #define MEM_HEAP_ERROR_PRINT (1 << 0)
69
70
71
72 // Signature of the expanded heap.
73 #define MEMi_EXPHEAP_SIGNATURE 0x45585048 // ('EXPH')
74 // Signature of the frame heap.
75 #define MEMi_FRMHEAP_SIGNATURE 0x46524D48 // ('FRMH')
76 // Signature of the unit heap.
77 #define MEMi_UNTHEAP_SIGNATURE 0x554E5448 // ('UNTH')
78 // User-defined signature.
79 #define MEMi_USRHEAP_SIGNATURE 0x55535248 // ('USRH')
80 // Block heap.
81 #define MEMi_BLKHEAP_SIGNATURE 0x424C4B48 // ('BLKH')
82
83 /* ========================================================================
84 enum Constant
85 ======================================================================== */
86
87 typedef enum
88 {
89 MEM_HEAP_TYPE_EXP, // Expanded heap.
90 MEM_HEAP_TYPE_FRM, // Frame heap.
91 MEM_HEAP_TYPE_UNIT, // Unit heap.
92 MEM_HEAP_TYPE_USER, // User-defined heap.
93 MEM_HEAP_TYPE_BLK, // Block heap.
94 MEM_HEAP_TYPE_UNKNOWN // Unknown heap handle.
95 }
96 MEMHeapType;
97
98 enum
99 {
100 MEM_HEAP_FILL_NOUSE, // When debug fill is not used.
101 MEM_HEAP_FILL_ALLOC, // When debug fill is allocated.
102 MEM_HEAP_FILL_FREE, // When debug fill is freed.
103 MEM_HEAP_FILL_MAX
104 };
105
106
107
108 /* =======================================================================
109 Type Definitions
110 ======================================================================== */
111 typedef OSSpinLock MEMSLock;
112
113 typedef struct MEMiHeapHead MEMiHeapHead;
114
115 // Common header among the heaps.
116 struct MEMiHeapHead
117 {
118 u32 signature;
119
120 MEMLink link;
121 MEMList childList;
122
123 void* heapStart; // Heap start address.
124 void* heapEnd; // Heap end (+1) address.
125 // OSMutex mutex; // For exclusive use between threads.
126 MEMSLock slock; // Spin lock.
127
128 union // Attribute.
129 {
130 u32 val;
131 struct
132 {
133 u32 _reserved : 24;
134 u32 optFlag : 8; // Option flag.
135 }
136 fields;
137 }
138 attribute;
139 };
140
141
142 typedef MEMiHeapHead* MEMHeapHandle; // Type to represent the heap handle.
143
144
145 /* =======================================================================
146 Function Prototypes
147 ======================================================================== */
148
149 MEMHeapHandle MEMFindContainHeap( const void* memBlock );
150
151 MEMHeapHandle MEMFindParentHeap( MEMHeapHandle heap );
152
153
154 /* ========================================================================
155 Inline Functions
156 ======================================================================== */
157
158 /*---------------------------------------------------------------------------*
159 Name: MEMGetHeapStartAddress
160
161 Description: Gets the start address of the memory area used by the heap.
162
163 Arguments: heap: Heap handle.
164
165 Returns: Returns the start address of the memory area used by the heap.
166 *---------------------------------------------------------------------------*/
167 static inline void*
MEMGetHeapStartAddress(MEMHeapHandle heap)168 MEMGetHeapStartAddress( MEMHeapHandle heap )
169 {
170 if (heap->signature == MEMi_BLKHEAP_SIGNATURE)
171 return heap->heapStart;
172 return (void*)heap;
173 }
174
175 /*---------------------------------------------------------------------------*
176 Name: MEMGetHeapStartAddressUsable
177
178 Description: Gets the start address of the memory area assigned by the heap.
179
180 Arguments: heap: Heap handle.
181
182 Returns: Returns the start address of the memory area assigned by the heap.
183 *---------------------------------------------------------------------------*/
184 static inline void*
MEMGetHeapStartAddressUsable(MEMHeapHandle heap)185 MEMGetHeapStartAddressUsable( MEMHeapHandle heap )
186 {
187 return heap->heapStart;
188 }
189
190 /*---------------------------------------------------------------------------*
191 Name: MEMGetHeapEndAddress
192
193 Description: Gets the end address +1 of the memory area used by the heap.
194
195 Arguments: heap: Heap handle.
196
197 Returns: Return the end address +1 of the memory area used by the heap.
198 *---------------------------------------------------------------------------*/
199 static inline void*
MEMGetHeapEndAddress(MEMHeapHandle heap)200 MEMGetHeapEndAddress( MEMHeapHandle heap )
201 {
202 return heap->heapEnd;
203 }
204
205 /*---------------------------------------------------------------------------*
206 Name: MEMGetHeapTotalUsableSize
207
208 Description: Gets the memory size allocated to the heap.
209 The header is not included.
210
211 Arguments: heap: Heap handle.
212
213 Returns: Returns the memory size allocated to the heap. The header is not included.
214 *---------------------------------------------------------------------------*/
215 static inline s32
MEMGetHeapTotalUsableSize(MEMHeapHandle heap)216 MEMGetHeapTotalUsableSize( MEMHeapHandle heap )
217 {
218 return ((s32)(heap->heapEnd) - (s32)(heap->heapStart));
219 }
220
221 /*---------------------------------------------------------------------------*
222 Name: MemGetHeapTotalSize
223
224 Description: Gets the memory size allocated to the heap
225 (including that of the header).
226
227 Arguments: heap Heap handle.
228
229 Returns: Returns the memory size allocated to the heap (total memory size including header).
230
231 *---------------------------------------------------------------------------*/
232 static inline s32
MEMGetHeapTotalSize(MEMHeapHandle heap)233 MEMGetHeapTotalSize( MEMHeapHandle heap )
234 {
235 if (heap->signature == MEMi_BLKHEAP_SIGNATURE)
236 return ((s32)(heap->heapEnd) - (s32)(heap->heapStart));
237 return ((s32)(heap->heapEnd) - (s32)(heap));
238 }
239
240
241 /*---------------------------------------------------------------------------*
242 Name: MEMGetHeapType
243
244 Description: Gets the type of heap specific to the heap handle.
245
246 Arguments: heap: Heap handle.
247
248 Returns: Gets the heap type from the heap handle.
249 *---------------------------------------------------------------------------*/
250 static inline MEMHeapType
MEMGetHeapType(MEMHeapHandle heap)251 MEMGetHeapType( MEMHeapHandle heap )
252 {
253 switch ( heap->signature )
254 {
255 case MEMi_EXPHEAP_SIGNATURE: return MEM_HEAP_TYPE_EXP;
256 case MEMi_FRMHEAP_SIGNATURE: return MEM_HEAP_TYPE_FRM;
257 case MEMi_UNTHEAP_SIGNATURE: return MEM_HEAP_TYPE_UNIT;
258 case MEMi_USRHEAP_SIGNATURE: return MEM_HEAP_TYPE_USER;
259 case MEMi_BLKHEAP_SIGNATURE: return MEM_HEAP_TYPE_BLK;
260 default: return MEM_HEAP_TYPE_UNKNOWN;
261 }
262 }
263
264
265 /*---------------------------------------------------------------------------*
266 Name: MEMIsExpHeap
267
268 Description: Determines whether the heap handle is for an expanded heap.
269
270 Arguments: heap Heap handle.
271
272 Returns: Returns true if it is for an expanded heap.
273 Returns false otherwise.
274 *---------------------------------------------------------------------------*/
275 static inline BOOL
MEMIsExpHeap(MEMHeapHandle heap)276 MEMIsExpHeap( MEMHeapHandle heap )
277 {
278 return ( heap->signature == MEMi_EXPHEAP_SIGNATURE );
279 }
280
281
282 /*---------------------------------------------------------------------------*
283 Name: MEMIsFrmHeap
284
285 Description: Determines whether the heap handle is for a frame heap.
286
287 Arguments: heap Heap handle.
288
289 Returns: Returns true if it is for a frame heap.
290 Returns false otherwise.
291 *---------------------------------------------------------------------------*/
292 static inline BOOL
MEMIsFrmHeap(MEMHeapHandle heap)293 MEMIsFrmHeap( MEMHeapHandle heap )
294 {
295 return ( heap->signature == MEMi_FRMHEAP_SIGNATURE );
296 }
297
298
299 /*---------------------------------------------------------------------------*
300 Name: MEMIsUnitHeap
301
302 Description: Determines whether the heap handle is for a unit heap.
303
304 Arguments: heap Heap handle.
305
306 Returns: Returns true if it is for a unit heap.
307 Returns false otherwise.
308 *---------------------------------------------------------------------------*/
309 static inline BOOL
MEMIsUnitHeap(MEMHeapHandle heap)310 MEMIsUnitHeap( MEMHeapHandle heap )
311 {
312 return ( heap->signature == MEMi_UNTHEAP_SIGNATURE );
313 }
314
315
316 /*---------------------------------------------------------------------------*
317 Name: MEMIsBlockHeap
318
319 Description: Determines whether a heap is a block heap.
320
321 Arguments: heap Heap handle.
322
323 Returns: Returns true if it is a block heap.
324 *---------------------------------------------------------------------------*/
325 static inline BOOL
MEMIsBlockHeap(MEMHeapHandle heap)326 MEMIsBlockHeap( MEMHeapHandle heap )
327 {
328 return ( heap->signature == MEMi_BLKHEAP_SIGNATURE );
329 }
330
331
332
333 /* =======================================================================
334 Debug Functions
335 ======================================================================== */
336
337 void MEMDumpHeap( MEMHeapHandle heap );
338 BOOL MEMCheckHeap( MEMHeapHandle heap );
339
340 u32 MEMSetFillValForHeap( int type, u32 val );
341 u32 MEMGetFillValForHeap( int type );
342
343
344 #ifdef __cplusplus
345 } /* extern "C" */
346 #endif
347
348 /* MEM_HEAPCOMMON_H__ */
349 #endif
350
351