1 /*---------------------------------------------------------------------------*
2 Project: TwlSDK - OS - include
3 File: alloc.h
4
5 Copyright 2003-2008 Nintendo. All rights reserved.
6
7 These coded instructions, statements, and computer programs contain
8 proprietary information of Nintendo of America Inc. and/or Nintendo
9 Company Ltd., and are protected by Federal copyright law. They may
10 not be disclosed to third parties or copied or duplicated in any form,
11 in whole or in part, without the prior written consent of Nintendo.
12
13 $Date:: 2008-09-17#$
14 $Rev: 8556 $
15 $Author: okubata_ryoma $
16 *---------------------------------------------------------------------------*/
17
18 #ifndef NITRO_OS_ALLOC_H_
19 #define NITRO_OS_ALLOC_H_
20
21 #include <nitro/misc.h>
22 #include <nitro/types.h>
23 #include <nitro/os/common/arena.h>
24
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28
29 //----------------------------------------------------------------
30 // type definition
31
32 typedef int OSHeapHandle;
33 typedef void (*OSAllocVisitor) (void *obj, u32 size);
34
35 #define OS_CURRENT_HEAP_HANDLE ((OSHeapHandle)-1)
36
37 //================================================================================
38 /*---------------------------------------------------------------------------*
39 Name: OS_InitAlloc
40
41 Description: Initializes the arena in which all heaps will reside.
42 Reserves some small amount of memory for array of heap
43 descriptors.
44
45 Arguments: id : arena ID
46 arenaStart : beginning addr of arena
47 arenaEnd : ending addr of arena
48 maxHeaps : Maximum number of active heaps that will be
49 : used in lifetime of program
50
51 Returns: start of real arena, aligned with 32 bytes boundaries, after
52 heap array has been allocated
53 *---------------------------------------------------------------------------*/
54 extern void *OS_InitAlloc(OSArenaId id, void *arenaStart, void *arenaEnd, int maxHeaps);
55
56 /*---------------------------------------------------------------------------*
57 Name: OS_ClearAlloc
58
59 Description: Clear heap pointer system remember.
60 After calling this, you can call OS_InitAlloc() again.
61
62 Arguments: id : arena ID
63
64 Returns: None
65 *---------------------------------------------------------------------------*/
66 extern void OS_ClearAlloc(OSArenaId id);
67
68 /*---------------------------------------------------------------------------*
69 Name: OS_CreateHeap
70
71 Description: Reserves area of memory from /start/ to /end/ for use as a
72 heap. Initializes heap descriptor and free list.
73 Will consume one entry in heap array.
74
75 Arguments: id : arena ID
76 start : starting addr of heap
77 end : ending addr of heap
78
79 Returns: If the function succeeds, it returns a new handle to heap
80 for use in OS_AllocFromHeap(), OS_FreeToHeap(), etc.
81 If the function fails, the return value is -1.
82 *---------------------------------------------------------------------------*/
83 extern OSHeapHandle OS_CreateHeap(OSArenaId id, void *start, void *end);
84
85 /*---------------------------------------------------------------------------*
86 Name: OS_DestroyHeap
87
88 Description: Frees up the descriptor for the /heap/. Subsequent
89 allocation requests from this heap will fail unless another
90 heap is created with the same handle.
91
92 Arguments: id : arena ID
93 heap : handle to a live heap, previously created with OS_CreateHeap().
94
95 Returns: None.
96 *---------------------------------------------------------------------------*/
97 extern void OS_DestroyHeap(OSArenaId id, OSHeapHandle heap);
98
99 /*---------------------------------------------------------------------------*
100 Name: OS_AddToHeap
101
102 Description: Adds an arbitrary block of memory to /heap/. Used to free
103 blocks previously allocated with OS_AllocFixed(), or to
104 create non-contiguous heaps.
105
106 Arguments: id : arena ID
107 heap : handle to live heap, previously created with OS_CreateHeap().
108 start : starting addr of block to add to /heap/
109 end : ending addr of block to add to /heap/
110
111 Returns: None.
112 *---------------------------------------------------------------------------*/
113 extern void OS_AddToHeap(OSArenaId id, OSHeapHandle heap, void *start, void *end);
114
115 /*---------------------------------------------------------------------------*
116 Name: OS_SetCurrentHeap
117
118 Description: Sets OSi_CurrentHeap to /heap/. All subsequent calls to
119 OS_Alloc() will be performed on this heap until another
120 call to OS_SetCurrentHeap().
121
122 Arguments: id : arena ID
123 heap : handle to a heap that was returned from OS_CreateHeap()
124
125 Returns: previous heap handle.
126 *---------------------------------------------------------------------------*/
127 extern OSHeapHandle OS_SetCurrentHeap(OSArenaId id, OSHeapHandle heap);
128
129 /*---------------------------------------------------------------------------*
130 Name: OS_AllocFromHeap
131
132 Description: Allocates /size/ bytes from /heap/. Some additional memory
133 will also be consumed from /heap/.
134
135 Arguments: id : arena ID
136 heap : handle to a heap that was returned from OS_CreateHeap()
137 size : size of object to be allocated
138
139 Returns: a null pointer or a pointer to the allocated space aligned
140 with ALIGNMENT bytes boundaries
141 *---------------------------------------------------------------------------*/
142 extern void *OS_AllocFromHeap(OSArenaId id, OSHeapHandle heap, u32 size);
143
144 /*---------------------------------------------------------------------------*
145 Name: OS_AllocFixed
146
147 Description: Allocates the block of memory specified by /rstart/ and
148 /rend/. Will break up any heap. Will not check for overlap
149 with other fixed blocks. May create a zero-length heap.
150
151 Arguments: id : arena ID
152 rstart : pointer to starting addr of block
153 rend : pointer to ending addr of block
154
155 Returns: a null pointer or a pointer to the allocated space aligned
156 with ALIGNMENT bytes boundaries. /rstart/ and /rend/ might be
157 adjusted to the boundaries of really allocated region.
158 *---------------------------------------------------------------------------*/
159 extern void *OS_AllocFixed(OSArenaId id, void **rstart, void **rend);
160
161 /*---------------------------------------------------------------------------*
162 Name: OS_FreeToHeap
163
164 Description: Returns obj /ptr/ to /heap/.
165
166 Arguments: id : arena ID
167 heap : handle to the heap that /ptr/ was allocated from
168 ptr : pointer to object previously returned from
169 OS_Alloc() or OS_AllocFromHeap().
170
171 Returns: None.
172 *---------------------------------------------------------------------------*/
173 extern void OS_FreeToHeap(OSArenaId id, OSHeapHandle heap, void *ptr);
174
175 /*---------------------------------------------------------------------------*
176 Name: OS_FreeAllToHeap
177
178 Description: free all allocated block in the specified heap
179
180 Arguments: id : arena ID
181 heap : handle to the heap
182
183 Returns: None.
184 *---------------------------------------------------------------------------*/
185 extern void OS_FreeAllToHeap(OSArenaId id, OSHeapHandle heap);
186
187 /*---------------------------------------------------------------------------*
188 Name: OS_CheckHeap
189
190 Description: Checks heap sanity for debugging
191
192 Arguments: id : arena ID
193 heap : handle to a live heap.
194
195 Returns: -1 if heap is not consistent. Otherwise, returns number
196 of bytes available in free.
197 *---------------------------------------------------------------------------*/
198 extern s32 OS_CheckHeap(OSArenaId id, OSHeapHandle heap);
199
200 /*---------------------------------------------------------------------------*
201 Name: OS_DumpHeap
202
203 Description: Dumps statistics and elements of a heap
204
205 Arguments: id : arena ID
206 heap : handle to a heap.
207
208 Returns: None.
209 *---------------------------------------------------------------------------*/
210 extern void OS_DumpHeap(OSArenaId id, OSHeapHandle heap);
211
212 /*---------------------------------------------------------------------------*
213 Name: OS_ReferentSize
214
215 Description: Returns size of payload
216
217 Arguments: id : arena ID
218 ptr : pointer to object previously returned from OS_Alloc()
219 or OSAllocFromHeap().
220
221 Returns: size of payload
222 *---------------------------------------------------------------------------*/
223 extern u32 OS_ReferentSize(OSArenaId id, void *ptr);
224
225 /*---------------------------------------------------------------------------*
226 Name: OS_VisitAllocated
227
228 Description: Visits every element of every allocated block of memory,
229 calling a routine on each one.
230
231 Arguments: id : arena ID
232 visitor : function to be called on each cell
233
234 Returns: None.
235 *---------------------------------------------------------------------------*/
236 extern void OS_VisitAllocated(OSArenaId id, OSAllocVisitor visitor);
237
238 /*---------------------------------------------------------------------------*
239 Name: OS_GetTotalAllocSize
240
241 Description: Get sum of allocated block size,
242 not including block header.
243
244 Arguments: id : arena ID
245 heap : handle to a heap.
246
247 Returns: sum of allocated block size
248 *---------------------------------------------------------------------------*/
249 extern u32 OSi_GetTotalAllocSize(OSArenaId id, OSHeapHandle heap, BOOL isHeadInclude);
OS_GetTotalAllocSize(OSArenaId id,OSHeapHandle heap)250 static inline u32 OS_GetTotalAllocSize(OSArenaId id, OSHeapHandle heap)
251 {
252 return OSi_GetTotalAllocSize(id, heap, FALSE);
253 }
254
255 /*---------------------------------------------------------------------------*
256 Name: OS_GetTotalOccupiedSize
257
258 Description: Get sum of allocated block size,
259 including block header.
260
261 Arguments: id : arena ID
262 heap : handle to a heap.
263
264 Returns: sum of allocated block size
265 *---------------------------------------------------------------------------*/
OS_GetTotalOccupiedSize(OSArenaId id,OSHeapHandle heap)266 static inline u32 OS_GetTotalOccupiedSize(OSArenaId id, OSHeapHandle heap)
267 {
268 return OSi_GetTotalAllocSize(id, heap, TRUE);
269 }
270
271 /*---------------------------------------------------------------------------*
272 Name: OS_GetTotalFreeSize
273
274 Description: Get sum of free block size,
275 not includeing of block header.
276
277 Arguments: id : arena ID
278 heap : handle to a heap.
279
280 Returns: sum of free block size
281 *---------------------------------------------------------------------------*/
282 extern u32 OS_GetTotalFreeSize(OSArenaId id, OSHeapHandle heap);
283
284 /*---------------------------------------------------------------------------*
285 Name: OS_GetMaxFreeSize
286
287 Description: Get maximun free block size
288
289 Arguments: id : arena ID
290 heap : handle to a heap.
291
292 Returns: maximum free block size.
293 *---------------------------------------------------------------------------*/
294 extern u32 OS_GetMaxFreeSize(OSArenaId id, OSHeapHandle heap);
295
296 /*---------------------------------------------------------------------------*
297 Name: OS_ClearHeap
298
299 Description: re-initialize heap.
300
301 Arguments: id : arena ID
302 heap : handle to a heap.
303
304 Returns: None.
305 *---------------------------------------------------------------------------*/
306 extern void OS_ClearHeap(OSArenaId id, OSHeapHandle heap, void *start, void *end);
307
308
309 //================================================================================
310 // convenient functions
311 //================================================================================
312 /*---------------------------------------------------------------------------*
313 Name: OS_AllocFromMain / OS_FreeToMain / OS_FreeAllToMain
314
315 Description: convenience Alloc/Free for access main memory,
316 Main-Processor private
317 *---------------------------------------------------------------------------*/
OS_AllocFromMain(u32 size)318 static inline void *OS_AllocFromMain(u32 size)
319 {
320 return OS_AllocFromHeap(OS_ARENA_MAIN, OS_CURRENT_HEAP_HANDLE, size);
321 }
OS_FreeToMain(void * ptr)322 static inline void OS_FreeToMain(void *ptr)
323 {
324 OS_FreeToHeap(OS_ARENA_MAIN, OS_CURRENT_HEAP_HANDLE, ptr);
325 }
OS_FreeAllToMain(void)326 static inline void OS_FreeAllToMain(void)
327 {
328 OS_FreeAllToHeap(OS_ARENA_MAIN, OS_CURRENT_HEAP_HANDLE);
329 }
330
331 /*---------------------------------------------------------------------------*
332 Name: OS_AllocFromSubPriv / OS_FreeToSubPriv / OS_FreeAllToSubPriv
333
334 Description: convenience Alloc/Free for access main memory,
335 Sub-Processor private
336 *---------------------------------------------------------------------------*/
OS_AllocFromSubPriv(u32 size)337 static inline void *OS_AllocFromSubPriv(u32 size)
338 {
339 return OS_AllocFromHeap(OS_ARENA_MAIN_SUBPRIV, OS_CURRENT_HEAP_HANDLE, size);
340 }
OS_FreeToSubPriv(void * ptr)341 static inline void OS_FreeToSubPriv(void *ptr)
342 {
343 OS_FreeToHeap(OS_ARENA_MAIN_SUBPRIV, OS_CURRENT_HEAP_HANDLE, ptr);
344 }
OS_FreeAllToSubPriv(void)345 static inline void OS_FreeAllToSubPriv(void)
346 {
347 OS_FreeAllToHeap(OS_ARENA_MAIN_SUBPRIV, OS_CURRENT_HEAP_HANDLE);
348 }
349
350 /*---------------------------------------------------------------------------*
351 Name: OS_AllocFromMainEx / OS_FreeToMainEx / OS_FreeAllToMainEx
352
353 Description: convenience Alloc/Free for extended main memory
354 *---------------------------------------------------------------------------*/
OS_AllocFromMainEx(u32 size)355 static inline void *OS_AllocFromMainEx(u32 size)
356 {
357 return OS_AllocFromHeap(OS_ARENA_MAINEX, OS_CURRENT_HEAP_HANDLE, size);
358 }
OS_FreeToMainEx(void * ptr)359 static inline void OS_FreeToMainEx(void *ptr)
360 {
361 OS_FreeToHeap(OS_ARENA_MAINEX, OS_CURRENT_HEAP_HANDLE, ptr);
362 }
OS_FreeAllToMainEx(void)363 static inline void OS_FreeAllToMainEx(void)
364 {
365 OS_FreeAllToHeap(OS_ARENA_MAINEX, OS_CURRENT_HEAP_HANDLE);
366 }
367
368 /*---------------------------------------------------------------------------*
369 Name: OS_AllocFromITCM / OS_FreeToITCM / OS_FreeAllToITCM
370
371 Description: convenience Alloc/Free for ITCM
372 *---------------------------------------------------------------------------*/
373 #ifdef SDK_ARM9
OS_AllocFromITCM(u32 size)374 static inline void *OS_AllocFromITCM(u32 size)
375 {
376 return OS_AllocFromHeap(OS_ARENA_ITCM, OS_CURRENT_HEAP_HANDLE, size);
377 }
OS_FreeToITCM(void * ptr)378 static inline void OS_FreeToITCM(void *ptr)
379 {
380 OS_FreeToHeap(OS_ARENA_ITCM, OS_CURRENT_HEAP_HANDLE, ptr);
381 }
OS_FreeAllToITCM(void)382 static inline void OS_FreeAllToITCM(void)
383 {
384 OS_FreeAllToHeap(OS_ARENA_ITCM, OS_CURRENT_HEAP_HANDLE);
385 }
386 #endif // SDK_ARM9
387
388 /*---------------------------------------------------------------------------*
389 Name: OS_AllocFromDTCM / OS_FreeToDTCM / OS_FreeAllToDTCM
390
391 Description: convenience Alloc/Free for DTCM
392 *---------------------------------------------------------------------------*/
393 #ifdef SDK_ARM9
OS_AllocFromDTCM(u32 size)394 static inline void *OS_AllocFromDTCM(u32 size)
395 {
396 return OS_AllocFromHeap(OS_ARENA_DTCM, OS_CURRENT_HEAP_HANDLE, size);
397 }
OS_FreeToDTCM(void * ptr)398 static inline void OS_FreeToDTCM(void *ptr)
399 {
400 OS_FreeToHeap(OS_ARENA_DTCM, OS_CURRENT_HEAP_HANDLE, ptr);
401 }
OS_FreeAllToDTCM(void)402 static inline void OS_FreeAllToDTCM(void)
403 {
404 OS_FreeAllToHeap(OS_ARENA_DTCM, OS_CURRENT_HEAP_HANDLE);
405 }
406 #endif
407
408 /*---------------------------------------------------------------------------*
409 Name: OS_AllocFromShared / OS_FreeToShared / OS_FreeAllToShared
410
411 Description: convenience Alloc/Free for shared memory
412 *---------------------------------------------------------------------------*/
OS_AllocFromShared(u32 size)413 static inline void *OS_AllocFromShared(u32 size)
414 {
415 return OS_AllocFromHeap(OS_ARENA_SHARED, OS_CURRENT_HEAP_HANDLE, size);
416 }
OS_FreeToShared(void * ptr)417 static inline void OS_FreeToShared(void *ptr)
418 {
419 OS_FreeToHeap(OS_ARENA_SHARED, OS_CURRENT_HEAP_HANDLE, ptr);
420 }
OS_FreeAllToShared(void)421 static inline void OS_FreeAllToShared(void)
422 {
423 OS_FreeAllToHeap(OS_ARENA_SHARED, OS_CURRENT_HEAP_HANDLE);
424 }
425
426 /*---------------------------------------------------------------------------*
427 Name: OS_AllocFromWramMain / OS_FreeToWramMain / OS_FreeAllToWramMain
428
429 Description: convenience Alloc/Free for common Work RAM,
430 Main-Processor private
431 *---------------------------------------------------------------------------*/
OS_AllocFromWramMain(u32 size)432 static inline void *OS_AllocFromWramMain(u32 size)
433 {
434 return OS_AllocFromHeap(OS_ARENA_WRAM_MAIN, OS_CURRENT_HEAP_HANDLE, size);
435 }
OS_FreeToWramMain(void * ptr)436 static inline void OS_FreeToWramMain(void *ptr)
437 {
438 OS_FreeToHeap(OS_ARENA_WRAM_MAIN, OS_CURRENT_HEAP_HANDLE, ptr);
439 }
OS_FreeAllToWramMain(void)440 static inline void OS_FreeAllToWramMain(void)
441 {
442 OS_FreeAllToHeap(OS_ARENA_WRAM_MAIN, OS_CURRENT_HEAP_HANDLE);
443 }
444
445 /*---------------------------------------------------------------------------*
446 Name: OS_AllocFromWramSub / OS_FreeToWramSub / OS_FreeAllToWramSub
447
448 Description: convenience Alloc/Free for common Work RAM,
449 Sub-Processor private
450 *---------------------------------------------------------------------------*/
OS_AllocFromWramSub(u32 size)451 static inline void *OS_AllocFromWramSub(u32 size)
452 {
453 return OS_AllocFromHeap(OS_ARENA_WRAM_SUB, OS_CURRENT_HEAP_HANDLE, size);
454 }
OS_FreeToWramSub(void * ptr)455 static inline void OS_FreeToWramSub(void *ptr)
456 {
457 OS_FreeToHeap(OS_ARENA_WRAM_SUB, OS_CURRENT_HEAP_HANDLE, ptr);
458 }
OS_FreeAllToWramSub(void)459 static inline void OS_FreeAllToWramSub(void)
460 {
461 OS_FreeAllToHeap(OS_ARENA_WRAM_SUB, OS_CURRENT_HEAP_HANDLE);
462 }
463
464 /*---------------------------------------------------------------------------*
465 Name: OS_AllocFromSubPrivWram / OS_FreeToSubPrivWram / OS_FreeAllToSubPrivWram
466
467 Description: convenience Alloc/Free for Sub-Processor private Work RAM
468 *---------------------------------------------------------------------------*/
OS_AllocFromSubPrivWram(u32 size)469 static inline void *OS_AllocFromSubPrivWram(u32 size)
470 {
471 return OS_AllocFromHeap(OS_ARENA_WRAM_SUBPRIV, OS_CURRENT_HEAP_HANDLE, size);
472 }
OS_FreeToSubPrivWram(void * ptr)473 static inline void OS_FreeToSubPrivWram(void *ptr)
474 {
475 OS_FreeToHeap(OS_ARENA_WRAM_SUBPRIV, OS_CURRENT_HEAP_HANDLE, ptr);
476 }
OS_FreeAllToSubPrivWram(void)477 static inline void OS_FreeAllToSubPrivWram(void)
478 {
479 OS_FreeAllToHeap(OS_ARENA_WRAM_SUBPRIV, OS_CURRENT_HEAP_HANDLE);
480 }
481
482 /*---------------------------------------------------------------------------*
483 Name: OS_Alloc
484
485 Description: same as OS_AllocFromMain() (if ARM9)
486 same as OS_AllocFromSubPriv() (if ARM7)
487 *---------------------------------------------------------------------------*/
488 #ifdef SDK_ARM9
489 # define OS_Alloc( size ) OS_AllocFromMain( (size) )
490 #else
491 # define OS_Alloc( size ) OS_AllocFromSubPriv( (size) )
492 #endif
493
494 /*---------------------------------------------------------------------------*
495 Name: OS_Free
496
497 Description: same as OS_FreeToMain() (if ARM9)
498 same as OS_FreeToSubPriv() (if ARM7)
499 *---------------------------------------------------------------------------*/
500 #ifdef SDK_ARM9
501 # define OS_Free( ptr ) OS_FreeToMain( (ptr) )
502 #else
503 # define OS_Free( ptr ) OS_FreeToSubPriv( (ptr) )
504 #endif
505
506 /*---------------------------------------------------------------------------*
507 Name: OS_FreeAll
508
509 Description: same as OS_FreeAllToMain() (if ARM9)
510 same as OS_FreeAllToSubPriv() (if ARM7)
511 *---------------------------------------------------------------------------*/
512 #ifdef SDK_ARM9
513 # define OS_FreeAll() OS_FreeAllToMain()
514 #else
515 # define OS_FreeAll() OS_FreeAllToSubPriv()
516 #endif
517
518 #ifdef __cplusplus
519 } /* extern "C" */
520 #endif
521
522 /* NITRO_OS_ALLOC_H_ */
523 #endif
524