1 /*---------------------------------------------------------------------------*
2 Project: TwlSDK - MI - include
3 File: cache.h
4
5 Copyright 2007-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-11-04#$
14 $Rev: 9197 $
15 $Author: yosizaki $
16 *---------------------------------------------------------------------------*/
17 #ifndef NITRO_MI_CACHE_H_
18 #define NITRO_MI_CACHE_H_
19
20
21 #include <nitro/misc.h>
22 #include <nitro/types.h>
23 #include <nitro/platform.h>
24 #include <nitro/mi/device.h>
25
26
27 #ifdef __cplusplus
28 extern "C"
29 {
30 #endif
31
32
33 /*---------------------------------------------------------------------------*/
34 /* Declarations */
35
36 /* The various pages' information that comprise the memory cache. */
37 typedef struct MICachePage
38 {
39 struct MICachePage *next; /* The next element (used for the list) */
40 u32 offset; /* The page header location (in page size units) */
41 u8 *buffer; /* The page buffer */
42 }
43 MICachePage;
44
45 /* Memory cache information structure */
46 typedef struct MICache
47 {
48 u32 pagewidth;
49 MICachePage *valid;
50 MICachePage *invalid;
51 MICachePage *loading;
52 int valid_total;
53 int invalid_total;
54 int loading_total;
55 }
56 MICache;
57
58 /* Macro to calculate the needed buffer size to prepare the specified page size and number of pages */
59 #define MI_CACHE_BUFFER_WORKSIZE(page, total) \
60 ((sizeof(MICachePage) + (page)) * (total))
61
62
63 /*---------------------------------------------------------------------------*/
64 /* Functions */
65
66 /*---------------------------------------------------------------------------*
67 Name: MI_InitCache
68
69 Description: Initializes the memory cache.
70
71 Arguments: cache The MICache structure to be initialized.
72 page The buffer size per page.
73 Must be a power of 2 if four or more pages.
74 buffer The buffer used for page management information.
75 length The buffer size.
76 This is divided into a number of page lists calculated as follows: length / (sizeof(MICachePage) + page)
77
78 It is guaranteed that the starting address in the buffer will be (buffer + N * page) for each page (N = 0, 1,...).
79
80
81 Returns: None.
82 *---------------------------------------------------------------------------*/
83 void MI_InitCache(MICache *cache, u32 page, void *buffer, u32 length);
84
85 /*---------------------------------------------------------------------------*
86 Name: MI_ReadCache
87
88 Description: Reads data from a cache.
89 Pages that are hit will be moved to the start of the valid list.
90 Pages that aren't hit are added to the load request list.
91
92 Arguments: cache The MICache structure.
93 buffer The transfer target memory.
94 If NULL is specified, simply request that the entire corresponding cache range be prepared without loading any data.
95
96 offset The transfer source offset.
97 length The transfer size.
98
99 Returns: TRUE if the entire region is hit by the cache.
100 *---------------------------------------------------------------------------*/
101 BOOL MI_ReadCache(MICache *cache, void *buffer, u32 offset, u32 length);
102
103 /*---------------------------------------------------------------------------*
104 Name: MI_LoadCache
105
106 Description: Runs the load process for all pages that exist in the load request list.
107 When the load request list is empty, control will be returned immediately without any processing. If a load request is added to the list during the function call, it will also be processed.
108
109
110 Note: Appropriate timing is required when calling this function from a context that allows devices to block.
111
112 Therefore, it must not be called from an interrupt handler, etc.
113
114 Arguments: cache The MICache structure.
115 device The device to be loaded.
116
117 Returns: None.
118 *---------------------------------------------------------------------------*/
119 void MI_LoadCache(MICache *cache, MIDevice *device);
120
121 /*---------------------------------------------------------------------------*
122 Name: MI_IsCacheLoading
123
124 Description: Determines whether the load request list is empty.
125 Load requests are added to the list by calls to the MI_ReadCache function and emptied by calls to the MI_LoadCache function.
126
127
128 Arguments: cache The MICache structure.
129
130 Returns: TRUE if the load request list is not empty.
131 *---------------------------------------------------------------------------*/
132 PLATFORM_ATTRIBUTE_INLINE
MI_IsCacheLoading(const MICache * cache)133 BOOL MI_IsCacheLoading(const MICache *cache)
134 {
135 return (cache->loading != NULL);
136 }
137
138
139 /*---------------------------------------------------------------------------*/
140
141
142 #ifdef __cplusplus
143 } /* extern "C" */
144 #endif
145
146
147 #endif /* NITRO_MI_CACHE_H_ */
148