1 /*---------------------------------------------------------------------------*
2 Project: TwlSDK - CARD - libraries
3 File: card_common.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:: 2009-01-13#$
14 $Rev: 9813 $
15 $Author: yosizaki $
16
17 *---------------------------------------------------------------------------*/
18 #ifndef NITRO_LIBRARIES_CARD_COMMON_H__
19 #define NITRO_LIBRARIES_CARD_COMMON_H__
20
21
22 #include <nitro/card/common.h>
23 #include <nitro/card/backup.h>
24
25
26 #include "../include/card_utility.h"
27 #include "../include/card_task.h"
28 #include "../include/card_command.h"
29
30
31
32 #ifdef __cplusplus
33 extern "C"
34 {
35 #endif
36
37
38 /*---------------------------------------------------------------------------*/
39 /* Constants */
40
41 // CARD internal state
42 enum
43 {
44 // Initialized
45 CARD_STAT_INIT = (1 << 0),
46
47 // PXI command initialized (ARM9)
48 CARD_STAT_INIT_CMD = (1 << 1),
49
50 // A command was issued but has not completed. (ARM9)
51 // This also includes the state before processing in the WaitForTask function.
52 CARD_STAT_BUSY = (1 << 2),
53
54 // There is a transferred task (ARM9/ARM7)
55 CARD_STAT_TASK = (1 << 3),
56
57 // Waiting to be notified that a request from the ARM7 has completed (ARM9)
58 CARD_STAT_WAITFOR7ACK = (1 << 5),
59
60 // Currently requesting cancellation
61 CARD_STAT_CANCEL = (1 << 6)
62 };
63
64 #define CARD_UNSYNCHRONIZED_BUFFER (void*)0x80000000
65
66 typedef enum
67 {
68 CARD_TARGET_NONE,
69 CARD_TARGET_ROM,
70 CARD_TARGET_BACKUP,
71 CARD_TARGET_RW
72 }
73 CARDTargetMode;
74
75 typedef u32 CARDAccessLevel;
76 #define CARD_ACCESS_LEVEL_NONE 0
77 #define CARD_ACCESS_LEVEL_BACKUP 1
78 #define CARD_ACCESS_LEVEL_ROM 2
79 #define CARD_ACCESS_LEVEL_FULL 3
80
81
82 /*---------------------------------------------------------------------------*/
83 /* Declarations */
84
85 typedef s32 CARDiOwner;
86
87 // CARD common parameters
88 typedef struct CARDiCommon
89 {
90 // Common memory for request communications
91 CARDiCommandArg *cmd;
92
93 // Status flag
94 volatile u32 flag;
95
96 // Default task priority
97 u32 priority;
98
99 #if defined(SDK_ARM9)
100 // Threshold value for invalidating the entire cache when reading from a ROM.
101 // FlushAll is more efficient than FlushRange past a fixed size.
102 u32 flush_threshold_ic;
103 u32 flush_threshold_dc;
104 #endif
105
106 // Card access rights management.
107 // Take exclusive control of the card/backup in the processor.
108 // This is necessary because multiple asynchronous functions (Rom and Backup) that use card access may be called from the same thread.
109 //
110 //
111 // This follows a lock-ID because OSMutex follows a thread
112 volatile CARDiOwner lock_owner; // ==s32 with Error status
113 volatile int lock_ref;
114 OSThreadQueue lock_queue[1];
115 CARDTargetMode lock_target;
116
117 // Task thread information
118 struct
119 {
120 OSThread context[1];
121 u8 stack[0x400];
122 }
123 thread;
124
125 #if defined(SDK_ARM7)
126 // New task procedure format
127 CARDTask task[1];
128 CARDTaskQueue task_q[1];
129 // The most recent command from the ARM9
130 int command;
131 u8 padding[20];
132 #else
133 // Old task procedure format
134 void (*task_func) (struct CARDiCommon *);
135 // User callback and arguments
136 MIDmaCallback callback;
137 void *callback_arg;
138 // Thread that waits for tasks to complete
139 OSThreadQueue busy_q[1];
140 // API task parameters
141 u32 src;
142 u32 dst;
143 u32 len;
144 u32 dma;
145 const CARDDmaInterface *DmaCall;
146 // Information for managing backup commands
147 CARDRequest req_type;
148 int req_retry;
149 CARDRequestMode req_mode;
150 OSThread *current_thread_9;
151 // u8 padding[32];
152 #endif
153
154 }
155 CARDiCommon;
156
157
158 SDK_COMPILER_ASSERT(sizeof(CARDiCommon) % 32 == 0);
159
160
161 /*---------------------------------------------------------------------------*/
162 /* Variables */
163
164 extern CARDiCommon cardi_common;
165 extern u32 cardi_rom_base;
166
167
168 /*---------------------------------------------------------------------------*/
169 /* functions */
170
171 /*---------------------------------------------------------------------------*
172 Name: CARDi_ExecuteOldTypeTask
173
174 Description: Gives asynchronous processing over to a worker thread, and runs synchronous processing here.
175 (It is up to this function's caller to guarantee that the task thread has already been locked for exclusive control by the CARDi_WaitForTask function)
176
177
178 Arguments: task Task function to set
179 async TRUE if asynchronous processing is desired.
180
181 Returns: None.
182 *---------------------------------------------------------------------------*/
183 BOOL CARDi_ExecuteOldTypeTask(void (*task) (CARDiCommon *), BOOL async);
184
185 /*---------------------------------------------------------------------------*
186 Name: CARDi_WaitForTask
187
188 Description: Waits until the task thread's usage rights are available.
189 (It is up to this function's caller to guarantee that the designated bus is locked)
190
191 Arguments: p The library's work buffer
192 restart TRUE if the next task should be started
193 callback Callback function after completion of access
194 callback_arg Argument of callback function
195
196 Returns: None.
197 *---------------------------------------------------------------------------*/
198 BOOL CARDi_WaitForTask(CARDiCommon *p, BOOL restart, MIDmaCallback callback, void *callback_arg);
199
200 /*---------------------------------------------------------------------------*
201 Name: CARDi_EndTask
202
203 Description: Sends a notification that a task is complete and releases the usage rights of the task thread.
204
205 Arguments: p Library's work buffer (passed by argument for efficiency)
206
207 Returns: None.
208 *---------------------------------------------------------------------------*/
209 void CARDi_EndTask(CARDiCommon *p);
210
211 void CARDi_OldTypeTaskThread(void *arg);
212
213
214 /*---------------------------------------------------------------------------*
215 Name: CARDi_GetTargetMode
216
217 Description: Gets the current lock target of the CARD bus.
218
219 Arguments: None.
220
221 Returns: One of the three states indicated by CARDTargetMode.
222 *---------------------------------------------------------------------------*/
CARDi_GetTargetMode(void)223 SDK_INLINE CARDTargetMode CARDi_GetTargetMode(void)
224 {
225 return cardi_common.lock_target;
226 }
227
228 /*---------------------------------------------------------------------------*
229 Name: CARDi_LockResource
230
231 Description: Resource exclusive lock
232
233 Arguments: owner lock-ID indicating the owner of the lock
234 target Resource target on the card bus to be locked
235
236 Returns: None.
237 *---------------------------------------------------------------------------*/
238 void CARDi_LockResource(CARDiOwner owner, CARDTargetMode target);
239
240 /*---------------------------------------------------------------------------*
241 Name: CARDi_UnlockResource
242
243 Description: Unlocks exclusive control of the resource.
244
245 Arguments: owner lock-ID indicating the owner of the lock
246 target Resource target on the card bus to be unlocked
247
248 Returns: None.
249 *---------------------------------------------------------------------------*/
250 void CARDi_UnlockResource(CARDiOwner owner, CARDTargetMode target);
251
252 /*---------------------------------------------------------------------------*
253 Name: CARDi_GetAccessLevel
254
255 Description: Gets the permitted ROM access level.
256
257 Arguments: None.
258
259 Returns: Permitted ROM access level.
260 *---------------------------------------------------------------------------*/
261 CARDAccessLevel CARDi_GetAccessLevel(void);
262
263 /*---------------------------------------------------------------------------*
264 Name: CARDi_WaitAsync
265
266 Description: Waits for asynchronous completion.
267
268 Arguments: None.
269
270 Returns: TRUE if the latest processing result is CARD_RESULT_SUCCESS.
271 *---------------------------------------------------------------------------*/
272 BOOL CARDi_WaitAsync(void);
273
274 /*---------------------------------------------------------------------------*
275 Name: CARDi_TryWaitAsync
276
277 Description: Attempts to wait for asynchronous completion and returns control immediately whether it succeeds or fails.
278
279 Arguments: None.
280
281 Returns: TRUE if the most recent asynchronous process has completed.
282 *---------------------------------------------------------------------------*/
283 BOOL CARDi_TryWaitAsync(void);
284
285 void CARDi_InitResourceLock(void);
286
287
288
289 void CARDi_InitCommand(void);
290
291
292 #ifdef __cplusplus
293 } // extern "C"
294 #endif
295
296
297
298 #endif // NITRO_LIBRARIES_CARD_COMMON_H__
299