1 /*---------------------------------------------------------------------------* 2 Project: TwlSDK - CTRDG - include 3 File: ctrdg_flash.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-18#$ 14 $Rev: 8573 $ 15 $Author: okubata_ryoma $ 16 *---------------------------------------------------------------------------*/ 17 18 #ifndef NITRO_CTRDG_FLASH_H_ 19 #define NITRO_CTRDG_FLASH_H_ 20 21 #include <nitro.h> 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 /* Definitions ****************************************************************/ 28 29 /* Flash header address */ 30 #define CTRDG_AGB_FLASH_ADR 0x0A000000 31 32 /* Maximum number of retries for the CTRDG_WriteAndVerifyAgbFlash function */ 33 #define CTRDG_AGB_FLASH_RETRY_MAX 3 34 35 36 typedef struct CTRDGiFlashSectorTag 37 { 38 u32 size; /* Sector size */ 39 u16 shift; /* Value after converting the sector size into a shift number */ 40 u16 count; /* Number of sectors */ 41 u16 top; /* The first usable sector number */ 42 u8 reserved[2]; /* Padding */ 43 } 44 CTRDGiFlashSector; 45 46 typedef struct CTRDGFlashTypeTag 47 { 48 u32 romSize; /* ROM size */ 49 CTRDGiFlashSector sector; /* Sector data (* see CTRDGiFlashSector above) */ 50 MICartridgeRamCycle agbWait[2]; /* AGB cartridge bus RAM region's read/write weight value */ 51 u16 makerID; /* Vendor ID */ 52 u16 deviceID; /* Device ID */ 53 } 54 CTRDGFlashType; 55 56 extern void CTRDGi_SetFlashBankMx(u16 bank); 57 extern u16 CTRDGi_ReadFlashID(void); 58 extern void StartFlashTimer(u16 phase); 59 extern void CheckFlashTimer(void); 60 extern void CTRDGi_SetFlashBankMx(u16 bank); 61 extern u16 CTRDGi_PollingSR512kCOMMON(u16 phase, u8 *adr, u16 lastData); 62 extern u16 CTRDGi_PollingSR1MCOMMON(u16 phase, u8 *adr, u16 lastData); 63 64 /*------------------------------------------------------------------*/ 65 /* Global variables */ 66 /*------------------------------------------------------------------*/ 67 68 /* 69 * Pointer to data that shows the structural content of flash memory. 70 * (For details, see the data definitions above) 71 */ 72 extern const CTRDGFlashType *AgbFlash; 73 74 /* 75 * Bar that shows progress during flash writes. 76 * NOTE: ctrdg_flash_remainder decreases by 128 at a time for Atmel flash memory and 1 at a time for other devices. 77 * 78 */ 79 extern u16 ctrdg_flash_remainder; 80 81 /*------------------------------------------------------------------*/ 82 /* Data read */ 83 /*------------------------------------------------------------------*/ 84 /*---------------------------------------------------------------------------* 85 Name: CTRDG_ReadAgbFlash 86 CTRDG_ReadAgbFlashAsync 87 88 Corresponding AGB function: extern void ReadFlash(u16 secNo,u32 offset,u8 *dst,u32 size) 89 90 Description: Starting from an address offset bytes into the target flash sector number, this function loads size bytes of data into the working memory area at dst. 91 92 93 Access cycle settings are made within the function, and do not need to occur in advance. 94 95 * Be aware that within this function the cartridge bus is locked for a fixed period of time. 96 97 98 Arguments: secNo: Target sector number 99 offset: The offset, in bytes, within the sector 100 dst: Address of the work region where the read data is stored 101 size: Read size in bytes 102 callback: The callback function invoked when the read process is complete (only for asynchronous functions). 103 104 Returns: None. 105 *---------------------------------------------------------------------------*/ 106 extern void CTRDG_ReadAgbFlash(u16 sec_num, u32 offset, u8 *dst, u32 size); 107 extern void CTRDG_ReadAgbFlashAsync(u16 sec_num, u32 offset, u8 *dst, u32 size, 108 CTRDG_TASK_FUNC callback); 109 110 111 /*------------------------------------------------------------------*/ 112 /* Chip erasure */ 113 /*------------------------------------------------------------------*/ 114 /*---------------------------------------------------------------------------* 115 Name: CTRDG_EraseAgbFlashChip 116 CTRDG_EraseAgbFlashChipAsync 117 118 Corresponding AGB function: extern u16 (*EraseFlashChip)() 119 120 Description: Completely erases the entire chip. 121 122 Access cycle settings are made within the function, and do not need to occur in advance. 123 As this function uses ticks to measure timeouts, the OS_InitTick function must be called in advance. 124 125 126 In addition, in the asynchronous versions, by referring to 'result', a member of the CTRDGTaskInfo structure that is an argument of the callback function returned after calling this routine, it is possible to know whether the Erase process succeeded. 127 128 129 * Be aware that within this function, all interrupts are prohibited for a certain period of time, and the cartridge bus is locked. 130 In particular, when calling this function do not use DMAs that automatically launch at specific times, such as direct sound, V/H-Blank synchronization, display synchronization, cartridge requests, etc. 131 132 133 134 Arguments: callback: The callback function invoked when the erase process is complete (only for asynchronous functions). 135 136 Returns: 0 : Normal completion (only for synchronous functions). 137 Non-zero: Erase error 138 *---------------------------------------------------------------------------*/ 139 extern u16 CTRDG_EraseAgbFlashChip(void); 140 extern void CTRDG_EraseAgbFlashChipAsync(CTRDG_TASK_FUNC callback); 141 142 143 /*------------------------------------------------------------------*/ 144 /* Sector deletion */ 145 /*------------------------------------------------------------------*/ 146 /*---------------------------------------------------------------------------* 147 Name: CTRDG_EraseAgbFlashSector 148 CTRDG_EraseAgbFlashSectorAsync 149 150 Corresponding AGB function: extern u16 (*EraseFlashSector)(u16 secNo) 151 152 Description: Erases the sector with the target sector number. 153 This routine will be called by the write routine, so it does not usually need to be called before performing a write. 154 155 An error is returned when the target sector number is out of range. 156 157 In addition, in the asynchronous versions, by referring to 'result', a member of the CTRDGTaskInfo structure that is an argument of the callback function returned after calling this routine, it is possible to know whether the Erase process succeeded. 158 159 160 Access cycle settings are made within the function, and do not need to occur in advance. 161 As this function uses ticks to measure timeouts, the OS_InitTick function must be called in advance. 162 163 164 * Be aware that within this function, all interrupts are prohibited for a certain period of time, and the cartridge bus is locked. 165 In particular, when calling this function do not use DMAs that automatically launch at specific times, such as direct sound, V/H-Blank synchronization, display synchronization, cartridge requests, etc. 166 167 168 169 Arguments: sec_num: Target sector number 170 callback: The callback function invoked when the erase process is complete (only for asynchronous functions). 171 172 Returns: 0 : Normal completion (only for synchronous functions). 173 Non-zero: Erase error 174 *---------------------------------------------------------------------------*/ 175 extern u16 CTRDG_EraseAgbFlashSector(u16 sec_num); 176 extern void CTRDG_EraseAgbFlashSectorAsync(u16 sec_num, CTRDG_TASK_FUNC callback); 177 178 179 /*------------------------------------------------------------------*/ 180 /* Per-sector data writes */ 181 /*------------------------------------------------------------------*/ 182 /*---------------------------------------------------------------------------* 183 Name: CTRDG_WriteAgbFlashSector 184 CTRDG_WriteAgbFlashSectorAsync 185 186 Corresponding AGB function: extern u16 (*ProgramFlashSector) (u16 secNo,u8 *src) 187 188 Description: Writes one sector's worth (4 KB) of data to the target sector number, starting at the src address. 189 Writes within this routine occur after the above CTRDG_EraseAgbFlashSector is called and the sector erased. 190 An error is returned when the target sector number is out of range. 191 As this routine runs, the global variable, ctrdg_flash_remainder, can be referenced to know how many bytes remain. 192 193 In addition, you can find out whether an asynchronous write process succeeded by checking the result member variable of the CTRDGTaskInfo structure, which is an argument to the callback function returned after this routine is called. 194 195 196 Access cycle settings are made within the function, and do not need to occur in advance. 197 As this function uses ticks to measure timeouts, the OS_InitTick function must be called in advance. 198 199 200 * Be aware that within this function, all interrupts are prohibited for a certain period of time, and the cartridge bus is locked. 201 In particular, when calling this function do not use DMAs that automatically launch at specific times, such as direct sound, V/H-Blank synchronization, display synchronization, cartridge requests, etc. 202 203 204 205 Arguments: sec_num: Target sector number 206 src: Write source address 207 callback: The callback function called when the write processes complete (only for asynchronous functions). 208 209 Returns: 0 : Normal completion (only for synchronous functions). 210 Non-zero: Write error 211 *---------------------------------------------------------------------------*/ 212 extern u16 CTRDG_WriteAgbFlashSector(u16 sec_num, u8 *src); 213 extern void CTRDG_WriteAgbFlashSectorAsync(u16 sec_num, u8 *src, CTRDG_TASK_FUNC callback); 214 215 216 /*------------------------------------------------------------------*/ 217 /* Per-byte data verification */ 218 /*------------------------------------------------------------------*/ 219 /*---------------------------------------------------------------------------* 220 Name: CTRDG_VerifyAgbFlash 221 CTRDG_VerifyAgbFlashAsync 222 223 Corresponding AGB function: extern u32 VerifyFlash(u16 secNo,u8 *src,u32 size) 224 225 Description: Verifies data starting from the 'src' address with target flash sector number data, in portions of 'size' bytes. 226 This function returns a 0 when verifies end normally, and when a verify error occurs, it returns the address where the error occurred. 227 In addition, in the asynchronous versions, by referring to 'result', a member of the CTRDGTaskInfo structure that is an argument of the callback function returned after calling this routine, it is possible to know whether the verification process succeeded. 228 229 230 Arguments: sec_num: Target sector number 231 src: The original address to verify (original data). 232 size: Verify size (bytes) 233 callback: The callback function called when the verification process completes (only for asynchronous functions) 234 235 Returns: 0 : Normal completion (only for synchronous functions). 236 Non-zero: Returns the device-side error address for a verify error. 237 *---------------------------------------------------------------------------*/ 238 extern u32 CTRDG_VerifyAgbFlash(u16 sec_num, u8 *src, u32 size); 239 extern void CTRDG_VerifyAgbFlashAsync(u16 sec_num, u8 *src, u32 size, CTRDG_TASK_FUNC callback); 240 241 242 /*------------------------------------------------------------------*/ 243 /* Per-sector data writes and per-byte verification */ 244 /*------------------------------------------------------------------*/ 245 /*---------------------------------------------------------------------------* 246 Name: CTRDG_WriteAndVerifyAgbFlash 247 CTRDG_WriteAndVerifyAgbFlashAsync 248 249 Corresponding AGB function: extern u32 ProgramFlashSectorEx2(u16 secNo, u8 *src, u32 verifySize) 250 251 Description: This function will call the CTRDG_WriteAgbFlashSector function to write data. After that, it will call the CTRDG_VerifyAgbFlash function to verify verifysize bytes. 252 253 When errors occur, retries are made up to a maximum of CTRDG_AGB_FLASH_RETRY_MAX (defined in ctrdg_flash.h) times. 254 255 NOTE: When there is a write error, this function uses 16 out of 32 bits to return the error code. When there is a verify error, however, a 32-bit device error address is returned. Take note of this when checking the error code. 256 257 258 In addition, in the asynchronous versions, by referring to 'result', a member of the CTRDGTaskInfo structure that is an argument of the callback function returned after calling this routine, it is possible to know whether the WriteAndVerify process succeeded. 259 260 261 Access cycle settings are made within the function, and do not need to occur in advance. 262 As this function uses ticks to measure timeouts, the OS_InitTick function must be called in advance. 263 264 265 * Be aware that within this function, all interrupts are prohibited for a certain period of time, and the cartridge bus is locked. 266 In particular, when calling this function do not use DMAs that automatically launch at specific times, such as direct sound, V/H-Blank synchronization, display synchronization, cartridge requests, etc. 267 268 269 270 Arguments: sec_num: Target sector number 271 src: Write source address 272 verifysize : Verify size (bytes) 273 callback: The callback function invoked when the WriteAndVerify process completes (only for asynchronous functions) 274 275 Returns: 0 : Normal completion (only for synchronous functions). 276 Non-zero: Returns the device-side error address for a verify error. 277 *---------------------------------------------------------------------------*/ 278 extern u32 CTRDG_WriteAndVerifyAgbFlash(u16 sec_num, u8 *src, u32 verifysize); 279 extern void CTRDG_WriteAndVerifyAgbFlashAsync(u16 sec_num, u8 *src, u32 verifysize, 280 CTRDG_TASK_FUNC callback); 281 282 283 #ifdef __cplusplus 284 } /* extern "C" */ 285 #endif 286 287 288 #endif /* NITRO_CTRDG_FLASH_H_ */ 289