1 /*---------------------------------------------------------------------------*
2 Project: TwlSDK - CTRDG - include
3 File: ctrdg_common.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:: 2009-01-28#$
14 $Rev: 9923 $
15 $Author: yada $
16 *---------------------------------------------------------------------------*/
17
18 #ifndef NITRO_CTRDG_COMMON_H_
19 #define NITRO_CTRDG_COMMON_H_
20
21
22 #include <nitro/types.h>
23 #include <nitro/memorymap.h>
24 #include <nitro/mi.h>
25 #include <nitro/os.h>
26 #include <nitro/pxi.h>
27
28
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32
33
34 //----------------------------------------------------------------------------
35
36 // Definitions Related to PXI Communications Protocol
37 #define CTRDG_PXI_COMMAND_MASK 0x0000003f // Command part for start word
38 #define CTRDG_PXI_COMMAND_SHIFT 0
39 #define CTRDG_PXI_COMMAND_PARAM_MASK 0x01ffffc0 // Parameter part for start word
40 #define CTRDG_PXI_COMMAND_PARAM_SHIFT 6
41 #define CTRDG_PXI_FIXLEN_DATA_MASK 0x03ffffff // Data part for fixed-length continuous packets
42 #define CTRDG_PXI_FIXLEN_DATA_SHIFT 0
43 #define CTRDG_PXI_FLEXLEN_DATA_MASK 0x01ffffff // Data part for variable-length continuous packets
44 #define CTRDG_PXI_FLEXLEN_DATA_SHIFT 0
45 #define CTRDG_PXI_FLEXLEN_CONTINUOUS_BIT 0x02000000 // Transferring variable-length continuous packets
46 #define CTRDG_PXI_PACKET_MAX 4 // Largest continuous number of packets
47
48 // Commands issued from ARM9 to the ARM7 via PXI
49 #define CTRDG_PXI_COMMAND_INIT_MODULE_INFO 0x0001
50 #define CTRDG_PXI_COMMAND_TERMINATE 0x0002
51 #define CTRDG_PXI_COMMAND_SET_PHI 0x0003
52
53 #define CTRDG_PXI_COMMAND_IMI_PACKET_SIZE 2
54
55 // Commands issued from ARM7 to the ARM9 via PXI
56 #define CTRDG_PXI_COMMAND_PULLED_OUT 0x0011
57 #define CTRDG_PXI_COMMAND_SET_PHI_RESULT 0x0012
58
59
60 #ifdef SDK_ARM9
61 #define CTRDG_LOCKED_BY_MYPROC_FLAG OS_MAINP_LOCKED_FLAG
62 #else
63 #define CTRDG_LOCKED_BY_MYPROC_FLAG OS_SUBP_LOCKED_FLAG
64 #endif
65
66 #define CTRDG_SYSROM9_NINLOGO_ADR 0xffff0020
67
68 #define CTRDG_AGB_ROMHEADER_SIZE 0xc0
69 #define CTRDG_AGB_NINLOGO_SIZE 0x9c
70
71 #define CTRDG_IS_ROM_CODE 0x96
72
73
74 //---- PHI Output Control
75 typedef enum
76 {
77 CTRDG_PHI_CLOCK_LOW = MIi_PHI_CLOCK_LOW, // Low level
78 CTRDG_PHI_CLOCK_4MHZ = MIi_PHI_CLOCK_4MHZ, // 4.19 MHz
79 CTRDG_PHI_CLOCK_8MHZ = MIi_PHI_CLOCK_8MHZ, // 8.38 MHz
80 CTRDG_PHI_CLOCK_16MHZ = MIi_PHI_CLOCK_16MHZ // 16.76 MHz
81 }
82 CTRDGPhiClock;
83
84 //----------------------------------------------------------------------------
85
86 // Game Pak header
87
88 typedef struct
89 {
90 u32 startAddress; // Start address (for AGB)
91 u8 nintendoLogo[0x9c]; // NINTENDO logo data (for AGB)
92
93 char titleName[12]; // Soft title name (for AGB)
94 u32 gameCode; // Game code (for AGB)
95 u16 makerCode; // Maker code (for AGB)
96
97 u8 isRomCode; // Is ROM code
98
99 u8 machineCode; // Machine code (for AGB)
100 u8 deviceType; // Device type (for AGB)
101
102 u8 exLsiID[3]; // Extended LSI-ID
103
104 u8 reserved_A[4]; // Reserved A (Set 0)
105 u8 softVersion; // Soft version (for AGB)
106 u8 complement; // Complement (for AGB)
107
108 u16 moduleID; // Module ID
109 }
110 CTRDGHeader;
111
112 // Peripheral devices ID
113
114 typedef struct
115 {
116 union
117 {
118 struct
119 {
120 u8 bitID; // Bit ID
121 u8 numberID:5; // Number ID
122 u8: 2;
123 u8 disableExLsiID:1; // Invalidate expanded LSI-ID region
124 };
125 u16 raw;
126 };
127 }
128 CTRDGModuleID;
129
130 // Peripheral devices information
131
132 typedef struct
133 {
134 CTRDGModuleID moduleID; // Module ID
135 u8 exLsiID[3]; // Extended LSI-ID
136 u8 isAgbCartridge:1; // Is AgbCartridge
137 u8 detectPullOut:1; // Detect pulled-out Game Pak
138 u8: 0;
139 u16 makerCode; // Maker code (for AGB)
140 u32 gameCode; // Game code (for AGB)
141 }
142 CTRDGModuleInfo;
143
144
145 //---- Callback type for pulled-out Game Pak
146 #ifdef SDK_ARM9
147 typedef BOOL (*CTRDGPulledOutCallback) (void);
148 #endif
149 /*---------------------------------------------------------------------------*
150
151 Description: About the CTRDG library
152
153 ARM7 periodically checks to see if the Game Pak has been removed.
154 However, this cannot be done if the ARM9 does not release its access rights to the cartridge bus, so do not keep a lock for more than 10 frames.
155
156
157
158 Internal processing locks the Game Pak, so control will not return until locks set by other processors are released.
159
160
161
162 However, if it has already been locked by this processor, you may call this without unlocking.
163
164
165 *---------------------------------------------------------------------------*/
166
167 /*---------------------------------------------------------------------------*
168 Name: CTRDGi_IsInitialized
169
170 Description: Checks whether the ctrdg library is initialized
171 (for internal use)
172
173 Arguments: None.
174
175 Returns: TRUE ... initialized already
176 FALSE... not initialized
177 *---------------------------------------------------------------------------*/
178 #ifndef SDK_TWLLTD
179 BOOL CTRDGi_IsInitialized(void);
180 #endif
181
182 /*---------------------------------------------------------------------------*
183 Name: CTRDG_Init
184
185 Description: Initializes the Game Pak.
186
187 Arguments: None.
188
189 Returns: None.
190 *---------------------------------------------------------------------------*/
191 #ifndef SDK_TWLLTD
192 void CTRDG_Init(void);
193 #else // SDK_TWLLTD
CTRDG_Init(void)194 SDK_INLINE void CTRDG_Init(void)
195 {
196 #ifdef SDK_ARM9
197 static BOOL isInitialized;
198
199 if (isInitialized)
200 {
201 return;
202 }
203 isInitialized = TRUE;
204
205 {
206 CTRDGModuleInfo *cip = (CTRDGModuleInfo *)HW_CTRDG_MODULE_INFO_BUF;
207
208 cip->moduleID.raw = 0xFFFF;
209 cip->exLsiID[0] = 0xFF;
210 cip->exLsiID[1] = 0xFF;
211 cip->exLsiID[2] = 0xFF;
212 cip->isAgbCartridge = FALSE;
213 cip->detectPullOut = FALSE;
214 cip->makerCode = 0xFFFF;
215 cip->gameCode = 0xFFFFFFFF;
216 }
217 #endif // SDK_ARM9
218 }
219 #endif // SDK_TWLLTD
220
221 /*---------------------------------------------------------------------------*
222 Name: CTRDG_DummyInit
223
224 Description: Initialize for setting CTRDG blank.
225 Called from the user-defined CTRDG_Init.
226
227 Arguments: None.
228
229 Returns: None.
230 *---------------------------------------------------------------------------*/
231 #if defined(SDK_ARM9) && !defined(SDK_TWLLTD)
232 void CTRDG_DummyInit(void);
233 #endif
234
235 /*---------------------------------------------------------------------------*
236 Name: CTRDG_IsPulledOut
237
238 Description: Checks to see if the Game Pak has been removed.
239
240 If the Game Pak was never inserted, the function returns FALSE.
241
242 If no resistance adapter Game Pak has been installed in the IS-NITRO-DEBUGGER, be aware that a Game Pak removal may be detected even if a Game Pak was never inserted.
243
244
245
246 Arguments: None.
247
248 Returns: TRUE if Game Pak removal detected
249 *---------------------------------------------------------------------------*/
250 BOOL CTRDG_IsPulledOut(void);
251
252 /*---------------------------------------------------------------------------*
253 Name: CTRDG_IsExisting
254
255 Description: Checks whether there is a Game Pak.
256
257 Arguments: None.
258
259 Returns: TRUE if existed
260 *---------------------------------------------------------------------------*/
261 BOOL CTRDG_IsExisting(void);
262
263 /*---------------------------------------------------------------------------*
264 Name: CTRDG_IsBitID
265
266 Description: Whether bit ID peripheral exists in the Game Pak.
267
268
269 Arguments: bitID bit ID
270
271 Returns: TRUE if existed
272 *---------------------------------------------------------------------------*/
273 BOOL CTRDG_IsBitID(u8 bitID);
274
275 /*---------------------------------------------------------------------------*
276 Name: CTRDG_IsNumberID
277
278 Description: Whether number ID peripheral exists in the Game Pak.
279
280 Arguments: numberID number ID
281
282 Returns: TRUE if existed
283 *---------------------------------------------------------------------------*/
284 BOOL CTRDG_IsNumberID(u8 numberID);
285
286 /*---------------------------------------------------------------------------*
287 Name: CTRDG_IsAgbCartridge
288
289 Description: Checks whether there is an AGB Game Pak.
290
291 Arguments: None.
292
293 Returns: TRUE if existed
294 *---------------------------------------------------------------------------*/
295 BOOL CTRDG_IsAgbCartridge(void);
296
297 /*---------------------------------------------------------------------------*
298 Name: CTRDG_IsOptionCartridge
299
300 Description: Checks whether there is an option Game Pak.
301
302 Arguments: None.
303
304 Returns: TRUE if existed
305 *---------------------------------------------------------------------------*/
306 BOOL CTRDG_IsOptionCartridge(void);
307
308 /*---------------------------------------------------------------------------*
309 Name: CTRDG_GetAgbGameCode
310
311 Description: Gets the AGB Game Pak's game code.
312
313 Arguments: None.
314
315 Returns: Game code if it exists, FALSE if it doesn't exist
316 *---------------------------------------------------------------------------*/
317 u32 CTRDG_GetAgbGameCode(void);
318
319 /*---------------------------------------------------------------------------*
320 Name: CTRDG_GetAgbMakerCode
321
322 Description: Gets the AGB Game Pak's maker code.
323
324 Arguments: None.
325
326 Returns: Maker code if it exists, FALSE if it doesn't exist
327 *---------------------------------------------------------------------------*/
328 u16 CTRDG_GetAgbMakerCode(void);
329
330 /*---------------------------------------------------------------------------*
331 Name: CTRDG_IsAgbCartridgePulledOut
332
333 Description: Get whether system has detected pulled-out AGB Game Pak.
334
335 Arguments: None.
336
337 Returns: TRUE if Game Pak removal detected
338 *---------------------------------------------------------------------------*/
339 BOOL CTRDG_IsAgbCartridgePulledOut(void);
340
341 /*---------------------------------------------------------------------------*
342 Name: CTRDG_IsOptionCartridgePulledOut
343
344 Description: get whether system has detected pulled-out option Game Pak.
345
346 Arguments: None.
347
348 Returns: TRUE if Game Pak removal detected
349 *---------------------------------------------------------------------------*/
350 BOOL CTRDG_IsOptionCartridgePulledOut(void);
351
352 /*---------------------------------------------------------------------------*
353 Name: CTRDG_SetPulledOutCallback
354
355 Description: Set user callback for being pulled-out Game Pak.
356
357 Arguments: callback: Callback
358
359 Returns: None.
360 *---------------------------------------------------------------------------*/
361 #ifdef SDK_ARM9
362 void CTRDG_SetPulledOutCallback(CTRDGPulledOutCallback callback);
363 #endif
364
365 /*---------------------------------------------------------------------------*
366 Name: CTRDG_TerminateForPulledOut
367
368 Description: Terminates for pulling out Game Pak.
369
370 Arguments: None.
371
372 Returns: None.
373 *---------------------------------------------------------------------------*/
374 #ifdef SDK_ARM9
375 void CTRDG_TerminateForPulledOut(void);
376 #endif
377
378 /*---------------------------------------------------------------------------*
379 Name: CTRDG_SendToARM7
380
381 Description: Sends data to ARM7.
382
383 Arguments: arg: data to send
384
385 Returns: None.
386 *---------------------------------------------------------------------------*/
387 void CTRDG_SendToARM7(void *arg);
388
389 //================================================================================
390 // ACCESS DATA IN CARTRIDGE
391 //================================================================================
392 /*---------------------------------------------------------------------------*
393 Name: CTRDG_DmaCopy16 / 32
394
395 Description: Reads Game Pak data via DMA.
396
397 Arguments: dmaNo: DMA No.
398 src: source address (in Game Pak)
399 dest: destination address (in memory)
400 size: forwarding size
401
402 Returns: TRUE if success.
403 FALSE if fail. (no Game Pak)
404 *---------------------------------------------------------------------------*/
405 BOOL CTRDG_DmaCopy16(u32 dmaNo, const void *src, void *dest, u32 size);
406 BOOL CTRDG_DmaCopy32(u32 dmaNo, const void *src, void *dest, u32 size);
407
408 /*---------------------------------------------------------------------------*
409 Name: CTRDG_CpuCopy8 / 16 / 32
410
411 Description: Reads Game Pak data by CPU access.
412
413 Arguments: src: source address (in Game Pak)
414 dest: destination address (in memory)
415 size: forwarding size
416
417 Returns: TRUE if success.
418 FALSE if fail. (no Game Pak)
419 *---------------------------------------------------------------------------*/
420 BOOL CTRDG_CpuCopy8(const void *src, void *dest, u32 size);
421 BOOL CTRDG_CpuCopy16(const void *src, void *dest, u32 size);
422 BOOL CTRDG_CpuCopy32(const void *src, void *dest, u32 size);
423
424 /*---------------------------------------------------------------------------*
425 Name: CTRDG_Read8 / 16 / 32
426
427 Description: Reads Game Pak data by CPU access.
428
429 Arguments: address: source address (in Game Pak)
430 rdata: address to store read data
431
432 Returns: TRUE if success.
433 FALSE if fail. (no Game Pak)
434 *---------------------------------------------------------------------------*/
435 BOOL CTRDG_Read8(const u8 *address, u8 *rdata);
436 BOOL CTRDG_Read16(const u16 *address, u16 *rdata);
437 BOOL CTRDG_Read32(const u32 *address, u32 *rdata);
438
439 /*---------------------------------------------------------------------------*
440 Name: CTRDG_Write8 / 16 / 32
441
442 Description: Writes data to Game Pak.
443
444 Arguments: address: destination address (in Game Pak)
445 data: data to write
446
447 Returns: TRUE if success.
448 FALSE if fail. (no Game Pak)
449 *---------------------------------------------------------------------------*/
450 BOOL CTRDG_Write8(u8 *address, u8 data);
451 BOOL CTRDG_Write16(u16 *address, u16 data);
452 BOOL CTRDG_Write32(u32 *address, u32 data);
453
454
455 /*---------------------------------------------------------------------------*
456 Name: CTRDG_IsEnabled
457
458 Description: Checks if CTRDG is accessible.
459
460 Arguments: None.
461
462 Returns: Returns Game Pak access permission.
463 *---------------------------------------------------------------------------*/
464 BOOL CTRDG_IsEnabled(void);
465
466 /*---------------------------------------------------------------------------*
467 Name: CTRDG_Enable
468
469 Description: Set Game Pak access permission mode.
470
471 Arguments: enable permission mode to be set.
472
473 Returns: None.
474 *---------------------------------------------------------------------------*/
475 void CTRDG_Enable(BOOL enable);
476
477 /*---------------------------------------------------------------------------*
478 Name: CTRDG_CheckEnabled
479
480 Description: Terminates program if CTRDG is not accessible.
481
482 Arguments: None.
483
484 Returns: None.
485 *---------------------------------------------------------------------------*/
486 void CTRDG_CheckEnabled(void);
487
488 /*---------------------------------------------------------------------------*
489 Name: CTRDG_CheckPulledOut
490
491 Description: Game Pak is pulled out.
492
493 Arguments: None.
494
495 Returns: None.
496 *---------------------------------------------------------------------------*/
497 void CTRDG_CheckPulledOut(void);
498
499
500 /*---------------------------------------------------------------------------*
501 Name: CTRDG_SetPhiClock
502
503 Description: Sets ARM7 and ARM9 PHI output clock.
504
505 Arguments: clock: Phi clock to set
506
507 Returns: None.
508 *---------------------------------------------------------------------------*/
509 #ifdef SDK_ARM9
510 void CTRDG_SetPhiClock(CTRDGPhiClock clock);
511 #endif
512
513
514 /*---------------------------------------------------------------------------*
515 Name: CTRDG_GetPhiClock
516
517 Description: Gets ARM7 and ARM9 PHI output clock setting.
518
519 Arguments: None.
520
521 Returns: Phi clock setting
522 *---------------------------------------------------------------------------*/
523 #ifdef SDK_ARM9
CTRDG_GetPhiClock(void)524 static inline CTRDGPhiClock CTRDG_GetPhiClock(void)
525 {
526 return (CTRDGPhiClock)MIi_GetPhiClock();
527 }
528 #endif
529
530 //================================================================================
531 // PRIVATE FUNCTION
532 //================================================================================
533 //---- Private function ( don't use these CTRDGi_* function )
534
535 // ROM access-cycle structure
536 typedef struct CTRDGRomCycle
537 {
538 MICartridgeRomCycle1st c1;
539 MICartridgeRomCycle2nd c2;
540
541 }
542 CTRDGRomCycle;
543
544 // Processor unit lock information structure
545 typedef struct CTRDGLockByProc
546 {
547 BOOL locked;
548 OSIntrMode irq;
549
550 }
551 CTRDGLockByProc;
552
553 void CTRDGi_InitCommon(void);
554 void CTRDGi_InitModuleInfo(void);
555 void CTRDGi_SendtoPxi(u32 data);
556 #if defined(SDK_ARM7)
557 BOOL CTRDGi_LockByProcessor(u16 lockID, CTRDGLockByProc *info);
558 #else
559 void CTRDGi_LockByProcessor(u16 lockID, CTRDGLockByProc *info);
560 #endif
561 void CTRDGi_UnlockByProcessor(u16 lockID, CTRDGLockByProc *info);
562 void CTRDGi_ChangeLatestAccessCycle(CTRDGRomCycle *r);
563 void CTRDGi_RestoreAccessCycle(CTRDGRomCycle *r);
564
565 BOOL CTRDGi_IsBitIDAtInit(u8 bitID);
566 BOOL CTRDGi_IsNumberIDAtInit(u8 numberID);
567 BOOL CTRDGi_IsAgbCartridgeAtInit(void);
568 u32 CTRDGi_GetAgbGameCodeAtInit(void);
569 u16 CTRDGi_GetAgbMakerCodeAtInit(void);
570
571 // Get the Game Pak header address
572 #define CTRDGi_GetHeaderAddr() ((CTRDGHeader *)HW_CTRDG_ROM)
573
574 // Get the ROM image address of the Game Pak peripheral ID
575 #define CTRDGi_GetModuleIDImageAddr() ((u16 *)(HW_CTRDG_ROM + 0x0001fffe))
576
577 // Get the address of the Game Pak peripheral information
578 #define CTRDGi_GetModuleInfoAddr() ((CTRDGModuleInfo *)HW_CTRDG_MODULE_INFO_BUF)
579
580
581
582
583 #define CTRDGi_FORWARD_TYPE_DMA 0x00000000
584 #define CTRDGi_FORWARD_TYPE_CPU 0x00000001
585 #define CTRDGi_FORWARD_TYPE_MASK 0x00000001
586
587 #define CTRDGi_FORWARD_WIDTH_8 0x00000000
588 #define CTRDGi_FORWARD_WIDTH_16 0x00000010
589 #define CTRDGi_FORWARD_WIDTH_32 0x00000020
590 #define CTRDGi_FORWARD_WIDTH_MASK 0x00000030
591
592 #define CTRDGi_FORWARD_DMA16 ( CTRDGi_FORWARD_TYPE_DMA | CTRDGi_FORWARD_WIDTH_16 )
593 #define CTRDGi_FORWARD_DMA32 ( CTRDGi_FORWARD_TYPE_DMA | CTRDGi_FORWARD_WIDTH_32 )
594 #define CTRDGi_FORWARD_CPU8 ( CTRDGi_FORWARD_TYPE_CPU | CTRDGi_FORWARD_WIDTH_8 )
595 #define CTRDGi_FORWARD_CPU16 ( CTRDGi_FORWARD_TYPE_CPU | CTRDGi_FORWARD_WIDTH_16 )
596 #define CTRDGi_FORWARD_CPU32 ( CTRDGi_FORWARD_TYPE_CPU | CTRDGi_FORWARD_WIDTH_32 )
597
598 #define CTRDGi_ACCESS_DIR_WRITE 0x00000000
599 #define CTRDGi_ACCESS_DIR_READ 0x00000001
600 #define CTRDGi_ACCESS_DIR_MASK 0x00000001
601
602 #define CTRDGi_ACCESS_WIDTH_8 0x00000010
603 #define CTRDGi_ACCESS_WIDTH_16 0x00000020
604 #define CTRDGi_ACCESS_WIDTH_32 0x00000040
605 #define CTRDGi_ACCESS_WIDTH_MASK 0x000000f0
606
607 #define CTRDGi_ACCESS_WRITE8 ( CTRDGi_ACCESS_DIR_WRITE | CTRDGi_ACCESS_WIDTH_8 )
608 #define CTRDGi_ACCESS_WRITE16 ( CTRDGi_ACCESS_DIR_WRITE | CTRDGi_ACCESS_WIDTH_16 )
609 #define CTRDGi_ACCESS_WRITE32 ( CTRDGi_ACCESS_DIR_WRITE | CTRDGi_ACCESS_WIDTH_32 )
610 #define CTRDGi_ACCESS_READ8 ( CTRDGi_ACCESS_DIR_READ | CTRDGi_ACCESS_WIDTH_8 )
611 #define CTRDGi_ACCESS_READ16 ( CTRDGi_ACCESS_DIR_READ | CTRDGi_ACCESS_WIDTH_16 )
612 #define CTRDGi_ACCESS_READ32 ( CTRDGi_ACCESS_DIR_READ | CTRDGi_ACCESS_WIDTH_32 )
613
614 //---- internal function
615 BOOL CTRDGi_CopyCommon(u32 dmaNo, const void *src, void *dest, u32 size, u32 forwardType);
616
617 //---- internal function
618 BOOL CTRDGi_AccessCommon(void *address, u32 data, void *rdata, u32 accessType);
619
620 #ifdef __cplusplus
621 } /* extern "C" */
622 #endif
623
624 /* NITRO_CTRDG_COMMON_H_ */
625 #endif
626